{"record":{"id":"8f8330e7fdde7ace","repo":"paperclipai/paperclip","slug":"unknown-config-key-warning-path-did-you-mean-8f8330","errorCode":null,"errorMessage":"Unknown config key ${warning.path}; did you mean ${warning.suggestion}? It will be preserved.","messagePattern":"Unknown config key (.+?); did you mean (.+?)\\? It will be preserved\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cli/src/commands/onboard.ts","lineNumber":375,"sourceCode":"  printPaperclipCliBanner();\n  p.intro(pc.bgCyan(pc.black(\" paperclipai onboard \")));\n  const configPath = resolveConfigPath(opts.config);\n  const instance = describeLocalInstancePaths(resolvePaperclipInstanceId());\n  p.log.message(\n    pc.dim(\n      `Local home: ${instance.homeDir} | instance: ${instance.instanceId} | config: ${configPath}`,\n    ),\n  );\n\n  let existingConfig: PaperclipConfig | null = null;\n  let invalidBackupPath: string | undefined;\n  if (configExists(opts.config)) {\n    p.log.message(pc.dim(`${configPath} exists`));\n\n    try {\n      existingConfig = readConfig(opts.config);\n      for (const warning of findPaperclipConfigKeyWarnings(existingConfig)) {\n        p.log.warn(`Unknown config key ${warning.path}; did you mean ${warning.suggestion}? It will be preserved.`);\n      }\n    } catch (err) {\n      const backupPath = backupInvalidConfig(opts.config);\n      p.log.warn(\n        `Existing config is invalid. Preserved the original bytes at ${backupPath}.\\n${err instanceof Error ? err.message : String(err)}`,\n      );\n\n      const canConfirmRepair =\n        opts.yes !== true &&\n        opts.invokedByRun !== true &&\n        process.stdin.isTTY === true &&\n        process.stdout.isTTY === true;\n      if (!canConfirmRepair) {\n        p.log.error(\n          `Refusing to replace ${configPath} without confirmation. Rerun interactively to repair from defaults; the original and ${backupPath} are unchanged.`,\n        );\n        p.outro(\"\");\n        process.exitCode = 1;","sourceCodeStart":357,"sourceCodeEnd":393,"githubUrl":"https://github.com/paperclipai/paperclip/blob/120ae5428fa29bee300bcf806491cd4d965fbb7c/cli/src/commands/onboard.ts#L357-L393","documentation":"Same warning as paperclipai configure, emitted during `paperclipai onboard` when an existing config file is found: readConfig succeeds, then findPaperclipConfigKeyWarnings reports keys that are not in paperclipConfigSchema with an edit-distance nearest-match suggestion. Unknown keys are preserved through the onboard merge (mergePaperclipConfig), so nothing is lost.","triggerScenarios":"Running `paperclipai onboard` over a config file containing typo'd keys, keys from another CLI version, or keys nested under the wrong section.","commonSituations":"Re-onboarding after a CLI downgrade; hand-edited config; team-shared config snippets with stale key names.","solutions":["Rename warning.path to warning.suggestion in the config file before continuing.","Remove keys left over from a different CLI version if nothing consumes them.","Let onboard finish, then run paperclipai configure to rewrite the file cleanly from the current schema.","Keep config edits minimal and let the CLI own key names."],"exampleFix":"// before\n$ paperclipai onboard --config ./paperclip.json\n! Unknown config key database.embeddedPostgresPort; did you mean database.embeddedPostgresDataDir?\n\n// after — fix the key in paperclip.json per the suggestion, re-run onboard","handlingStrategy":"validation","validationCode":"const config = JSON.parse(readFileSync(configPath, \"utf8\"));\nconst warnings = findPaperclipConfigKeyWarnings(config);\nif (warnings.length) {\n  for (const w of warnings) console.error(`${w.path} -> ${w.suggestion}`);\n  process.exitCode = 1; // fail config pipelines early\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run onboard with a config generated by the same CLI version to avoid version-skew keys.","Codify config in templates that pass findPaperclipConfigKeyWarnings before deploy.","Act on each warning at onboard time — suggestions in the message are the exact rename."],"tags":["config","schema","typo","cli","onboard"],"backgroundTag":"unknown-config-key","analyzedSha":"120ae5428fa29bee300bcf806491cd4d965fbb7c","analyzedAt":"2026-08-18T22:49:45.177Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}