slopus/happy · error · Error

No machine ID found in settings

Error message

No machine ID found in settings

What it means

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.

Source

Thrown at packages/happy-cli/src/agy/runAgy.ts:58

  verbose?: boolean;
}

export async function runAgy(opts: RunAgyOptions): Promise<void> {
  const verbose = opts.verbose === true;
  const sessionTag = randomUUID();
  connectionState.setBackend('agy');

  const log = (msg: string) => {
    logger.debug(`[agy] ${msg}`);
    if (verbose) {
      console.log(`[agy] ${msg}`);
    }
  };

  const api = await ApiClient.create(opts.credentials);
  const settings = await readSettings();
  if (!settings?.machineId) {
    throw new Error('No machine ID found in settings');
  }

  await api.getOrCreateMachine({
    machineId: settings.machineId,
    metadata: initialMachineMetadata,
  });

  const { state, metadata } = createSessionMetadata({
    flavor: 'agy',
    machineId: settings.machineId,
    startedBy: opts.startedBy,
  });
  const response = await api.getOrCreateSession({ tag: sessionTag, metadata, state });
  if (response) {
    log(`Happy Session ID: ${response.id}`);
  }

  let session: ApiSessionClient;

View on GitHub (pinned to b824cd0a46)

Solutions

1. Complete happy's authentication/setup once to generate settings with machineId.
2. Verify the settings file exists at the expected path with a machineId value.
3. Remove a corrupt settings file and re-authenticate to regenerate it.
4. Fix HOME/XDG environment variables so readSettings resolves the real settings path.

Example fix

// before
$ happy agy  // no settings on fresh container
// after
$ happy auth  # creates settings with machineId
$ happy agy

import { readSettings } from '...';
const settings = await readSettings();
if (!settings?.machineId) {
  console.error('Missing happy settings/machineId. Run `happy` auth setup first.');
  process.exit(1);
}

function hasMachineId(s: unknown): s is { machineId: string } & Record<string, unknown> {
  return typeof s === 'object' && s !== null && 'machineId' in s &&
    typeof (s as { machineId?: unknown }).machineId === 'string' &&
    (s as { machineId: string }).machineId.length > 0;
}

try {
  await runAgy(opts);
} catch (err) {
  if (err instanceof Error && err.message === 'No machine ID found in settings') {
    console.error('Run happy authentication once to generate settings with a machineId.');
    process.exit(1);
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: Docker/CI containers with no persisted happy settings; switching users or HOME dirs; manually pruned settings; fresh OS install.

Related errors

• No machine ID found in settings
• No machine ID found in settings
• Unknown agent: ${id}. Available agents: ${available}
• Claude local launcher not found. Please ensure HAPPY_PROJECT
• Daemon-spawned sessions cannot use local/interactive mode. U

AI-assisted analysis of slopus/happy@b824cd0a46 (2026-08-31). Data as JSON: /api/errors/b5d44363af256a73. Report an issue: GitHub.