{"record":{"id":"b5d44363af256a73","repo":"slopus/happy","slug":"no-machine-id-found-in-settings-b5d443","errorCode":null,"errorMessage":"No machine ID found in settings","messagePattern":"No machine ID found in settings","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/happy-cli/src/agy/runAgy.ts","lineNumber":58,"sourceCode":"  verbose?: boolean;\n}\n\nexport async function runAgy(opts: RunAgyOptions): Promise<void> {\n  const verbose = opts.verbose === true;\n  const sessionTag = randomUUID();\n  connectionState.setBackend('agy');\n\n  const log = (msg: string) => {\n    logger.debug(`[agy] ${msg}`);\n    if (verbose) {\n      console.log(`[agy] ${msg}`);\n    }\n  };\n\n  const api = await ApiClient.create(opts.credentials);\n  const settings = await readSettings();\n  if (!settings?.machineId) {\n    throw new Error('No machine ID found in settings');\n  }\n\n  await api.getOrCreateMachine({\n    machineId: settings.machineId,\n    metadata: initialMachineMetadata,\n  });\n\n  const { state, metadata } = createSessionMetadata({\n    flavor: 'agy',\n    machineId: settings.machineId,\n    startedBy: opts.startedBy,\n  });\n  const response = await api.getOrCreateSession({ tag: sessionTag, metadata, state });\n  if (response) {\n    log(`Happy Session ID: ${response.id}`);\n  }\n\n  let session: ApiSessionClient;","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/slopus/happy/blob/b824cd0a4681d41af631a8e422a813873e4455b0/packages/happy-cli/src/agy/runAgy.ts#L40-L76","documentation":"runAgy, like runAcp, requires the local happy settings to contain a machineId so it can call api.getOrCreateMachine to identify this machine. Missing settings or a missing machineId field aborts startup with this error.","triggerScenarios":"Running `happy agy` on a machine where settings were never created by the auth flow; settings file reset/corrupted; settings schema without machineId (old version); HOME pointing elsewhere so readSettings reads the wrong (empty) file.","commonSituations":"Docker/CI containers with no persisted happy settings; switching users or HOME dirs; manually pruned settings; fresh OS install.","solutions":["Complete happy's authentication/setup once to generate settings with machineId.","Verify the settings file exists at the expected path with a machineId value.","Remove a corrupt settings file and re-authenticate to regenerate it.","Fix HOME/XDG environment variables so readSettings resolves the real settings path."],"exampleFix":"// before\n$ happy agy  // no settings on fresh container\n// after\n$ happy auth  # creates settings with machineId\n$ happy agy","handlingStrategy":"validation","validationCode":"import { readSettings } from '...';\nconst settings = await readSettings();\nif (!settings?.machineId) {\n  console.error('Missing happy settings/machineId. Run `happy` auth setup first.');\n  process.exit(1);\n}","typeGuard":"function hasMachineId(s: unknown): s is { machineId: string } & Record<string, unknown> {\n  return typeof s === 'object' && s !== null && 'machineId' in s &&\n    typeof (s as { machineId?: unknown }).machineId === 'string' &&\n    (s as { machineId: string }).machineId.length > 0;\n}","tryCatchPattern":"try {\n  await runAgy(opts);\n} catch (err) {\n  if (err instanceof Error && err.message === 'No machine ID found in settings') {\n    console.error('Run happy authentication once to generate settings with a machineId.');\n    process.exit(1);\n  } else throw err;\n}","preventionTips":["Complete happy authentication before running agy on a fresh machine/container.","Cache/persist the settings file in CI so machineId survives runs.","Confirm HOME/XDG env vars resolve to the directory containing happy settings.","Re-authenticate after wiping or manually editing the settings file."],"tags":["settings","machine-id","configuration","onboarding"],"backgroundTag":"missing-settings-machine-id","analyzedSha":"b824cd0a4681d41af631a8e422a813873e4455b0","analyzedAt":"2026-08-31T23:12:36.205Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}