slopus/happy · warning

⚠️ Settings schema v${schemaVersion} > supported v${SUPPORTE

Error message

⚠️ Settings schema v${schemaVersion} > supported v${SUPPORTED_SCHEMA_VERSION}. Update happy-cli for full functionality.

What it means

readSettings() reads ~/.happy settings.json and checks its `schemaVersion` (defaulting to 1) against SUPPORTED_SCHEMA_VERSION. If the file was written by a newer happy-cli (or hand-edited) with a higher schema version, this warning is logged and the settings are still loaded without downgrade migration — but newer fields may be ignored, so the CLI tells you to update happy-cli for full functionality. It is a warning, not a failure: defaults are merged and the CLI continues.

Source

Thrown at packages/happy-cli/src/persistence.ts:97

  daemonLogPath?: string;
}

export async function readSettings(): Promise<Settings> {
  if (!existsSync(configuration.settingsFile)) {
    return { ...defaultSettings }
  }

  try {
    // Read raw settings
    const content = await readFile(configuration.settingsFile, 'utf8')
    const raw = JSON.parse(content)

    // Check schema version (default to 1 if missing)
    const schemaVersion = raw.schemaVersion ?? 1;

    // Warn if schema version is newer than supported
    if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {
      logger.warn(
        `⚠️ Settings schema v${schemaVersion} > supported v${SUPPORTED_SCHEMA_VERSION}. ` +
        'Update happy-cli for full functionality.'
      );
    }

    // Migrate if needed
    const migrated = migrateSettings(raw, schemaVersion);

    if (migrated.sandboxConfig !== undefined) {
      try {
        migrated.sandboxConfig = SandboxConfigSchema.parse(migrated.sandboxConfig);
      } catch (error: any) {
        logger.warn(`⚠️ Invalid sandbox config - skipping. Error: ${error.message}`);
        migrated.sandboxConfig = undefined;
      }
    }

    // Merge with defaults to ensure all required fields exist

View on GitHub (pinned to b824cd0a46)

Solutions

1. Update happy-cli to the latest version (`npm install -g happy-coder` or your package manager of choice) so it supports the settings schema on disk.
2. If you intentionally downgraded, either accept reduced functionality or delete/rename the settings file to regenerate defaults (back up API keys first).
3. Avoid sharing one ~/.happy directory between CLI versions (e.g. pin HAPPY_HOME_DIR per version in dev setups).
4. Verify the installed CLI version matches what you expect (`happy --version`) if the warning appeared after a version switch.

Example fix

// before: older CLI reading newer schema
// settings.json: { "schemaVersion": 3, ... } with CLI supporting v2 → warning
// after: upgrade the CLI
npm install -g happy-coder@latest  # now SUPPORTED_SCHEMA_VERSION >= 3, no warning

// Check the settings schema version before relying on the CLI
import { readFileSync, existsSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const settingsPath = join(homedir(), '.happy', 'settings.json');
if (existsSync(settingsPath)) {
  const raw = JSON.parse(readFileSync(settingsPath, 'utf8'));
  const SUPPORTED_SCHEMA_VERSION = 2; // match your installed CLI's constant
  if ((raw.schemaVersion ?? 1) > SUPPORTED_SCHEMA_VERSION) {
    console.warn(`Settings schema v${raw.schemaVersion} is newer than supported v${SUPPORTED_SCHEMA_VERSION} — update happy-cli`);
  }
}

function settingsSchemaIsSupported(raw: unknown, supported: number): boolean {
  return typeof raw === 'object' && raw !== null &&
    typeof (raw as any).schemaVersion === 'number' &&
    (raw as any).schemaVersion <= supported;
}

When it happens

Trigger: The settings file on disk contains `schemaVersion: N` where N > SUPPORTED_SCHEMA_VERSION — typically after using a newer happy-cli version (or a canary/beta build) that upgraded the settings schema, then switching back to an older installed CLI.

Common situations: Downgrading happy-cli via npm/pnpm after having run a newer release; switching between stable and main-branch dev builds of the CLI on the same machine; manually editing settings.json and bumping schemaVersion; syncing ~/.happy across machines with different CLI versions.

Related errors

• No machine ID found in settings
• No machine ID found in settings
• Claude clear goal action is not supported
• Claude edit goal action is not supported
• No machine ID found in settings

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