{"record":{"id":"56073fe9262a4f3e","repo":"slopus/happy","slug":"settings-schema-v-schemaversion-supported-v","errorCode":null,"errorMessage":"⚠️ Settings schema v${schemaVersion} > supported v${SUPPORTED_SCHEMA_VERSION}. Update happy-cli for full functionality.","messagePattern":"⚠️ Settings schema v(.+?) > supported v(.+?)\\. Update happy-cli for full functionality\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/happy-cli/src/persistence.ts","lineNumber":97,"sourceCode":"  daemonLogPath?: string;\n}\n\nexport async function readSettings(): Promise<Settings> {\n  if (!existsSync(configuration.settingsFile)) {\n    return { ...defaultSettings }\n  }\n\n  try {\n    // Read raw settings\n    const content = await readFile(configuration.settingsFile, 'utf8')\n    const raw = JSON.parse(content)\n\n    // Check schema version (default to 1 if missing)\n    const schemaVersion = raw.schemaVersion ?? 1;\n\n    // Warn if schema version is newer than supported\n    if (schemaVersion > SUPPORTED_SCHEMA_VERSION) {\n      logger.warn(\n        `⚠️ Settings schema v${schemaVersion} > supported v${SUPPORTED_SCHEMA_VERSION}. ` +\n        'Update happy-cli for full functionality.'\n      );\n    }\n\n    // Migrate if needed\n    const migrated = migrateSettings(raw, schemaVersion);\n\n    if (migrated.sandboxConfig !== undefined) {\n      try {\n        migrated.sandboxConfig = SandboxConfigSchema.parse(migrated.sandboxConfig);\n      } catch (error: any) {\n        logger.warn(`⚠️ Invalid sandbox config - skipping. Error: ${error.message}`);\n        migrated.sandboxConfig = undefined;\n      }\n    }\n\n    // Merge with defaults to ensure all required fields exist","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/slopus/happy/blob/b824cd0a4681d41af631a8e422a813873e4455b0/packages/happy-cli/src/persistence.ts#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If you intentionally downgraded, either accept reduced functionality or delete/rename the settings file to regenerate defaults (back up API keys first).","Avoid sharing one ~/.happy directory between CLI versions (e.g. pin HAPPY_HOME_DIR per version in dev setups).","Verify the installed CLI version matches what you expect (`happy --version`) if the warning appeared after a version switch."],"exampleFix":"// before: older CLI reading newer schema\n// settings.json: { \"schemaVersion\": 3, ... } with CLI supporting v2 → warning\n// after: upgrade the CLI\nnpm install -g happy-coder@latest  # now SUPPORTED_SCHEMA_VERSION >= 3, no warning","handlingStrategy":"validation","validationCode":"// Check the settings schema version before relying on the CLI\nimport { readFileSync, existsSync } from 'fs';\nimport { homedir } from 'os';\nimport { join } from 'path';\n\nconst settingsPath = join(homedir(), '.happy', 'settings.json');\nif (existsSync(settingsPath)) {\n  const raw = JSON.parse(readFileSync(settingsPath, 'utf8'));\n  const SUPPORTED_SCHEMA_VERSION = 2; // match your installed CLI's constant\n  if ((raw.schemaVersion ?? 1) > SUPPORTED_SCHEMA_VERSION) {\n    console.warn(`Settings schema v${raw.schemaVersion} is newer than supported v${SUPPORTED_SCHEMA_VERSION} — update happy-cli`);\n  }\n}","typeGuard":"function settingsSchemaIsSupported(raw: unknown, supported: number): boolean {\n  return typeof raw === 'object' && raw !== null &&\n    typeof (raw as any).schemaVersion === 'number' &&\n    (raw as any).schemaVersion <= supported;\n}","tryCatchPattern":null,"preventionTips":["Keep happy-cli updated whenever the settings schema moves forward; don't run old CLIs against settings written by newer ones.","Avoid switching the same machine between stable and dev/canary CLI builds that share one ~/.happy directory.","Don't hand-edit `schemaVersion` in settings.json.","Back up settings (and keys) before downgrading the CLI, and treat this warning as a cue to upgrade, not to re-edit the file."],"tags":["settings","schema-version","migration","versioning"],"backgroundTag":"schema-version-too-new","analyzedSha":"b824cd0a4681d41af631a8e422a813873e4455b0","analyzedAt":"2026-08-31T23:12:36.205Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}