Unknown config key ${warning.path}; did you mean ${warning.s

Error message

Unknown config key ${warning.path}; did you mean ${warning.suggestion}? It will be preserved.

What it means

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.

Source

Thrown at cli/src/commands/onboard.ts:375

  printPaperclipCliBanner();
  p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));
  const configPath = resolveConfigPath(opts.config);
  const instance = describeLocalInstancePaths(resolvePaperclipInstanceId());
  p.log.message(
    pc.dim(
      `Local home: ${instance.homeDir} | instance: ${instance.instanceId} | config: ${configPath}`,
    ),
  );

  let existingConfig: PaperclipConfig | null = null;
  let invalidBackupPath: string | undefined;
  if (configExists(opts.config)) {
    p.log.message(pc.dim(`${configPath} exists`));

    try {
      existingConfig = readConfig(opts.config);
      for (const warning of findPaperclipConfigKeyWarnings(existingConfig)) {
        p.log.warn(`Unknown config key ${warning.path}; did you mean ${warning.suggestion}? It will be preserved.`);
      }
    } catch (err) {
      const backupPath = backupInvalidConfig(opts.config);
      p.log.warn(
        `Existing config is invalid. Preserved the original bytes at ${backupPath}.\n${err instanceof Error ? err.message : String(err)}`,
      );

      const canConfirmRepair =
        opts.yes !== true &&
        opts.invokedByRun !== true &&
        process.stdin.isTTY === true &&
        process.stdout.isTTY === true;
      if (!canConfirmRepair) {
        p.log.error(
          `Refusing to replace ${configPath} without confirmation. Rerun interactively to repair from defaults; the original and ${backupPath} are unchanged.`,
        );
        p.outro("");
        process.exitCode = 1;

View on GitHub (pinned to 120ae5428f)

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.

Example fix

// before
$ paperclipai onboard --config ./paperclip.json
! Unknown config key database.embeddedPostgresPort; did you mean database.embeddedPostgresDataDir?

// after — fix the key in paperclip.json per the suggestion, re-run onboard

Defensive patterns

Strategy: validation

Validate before calling

const config = JSON.parse(readFileSync(configPath, "utf8"));
const warnings = findPaperclipConfigKeyWarnings(config);
if (warnings.length) {
  for (const w of warnings) console.error(`${w.path} -> ${w.suggestion}`);
  process.exitCode = 1; // fail config pipelines early
}

Prevention

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.

When it happens

Trigger: Running `paperclipai onboard` over a config file containing typo'd keys, keys from another CLI version, or keys nested under the wrong section.

Common situations: Re-onboarding after a CLI downgrade; hand-edited config; team-shared config snippets with stale key names.

Related errors

AI-assisted analysis of paperclipai/paperclip@120ae5428f (2026-08-18). Data as JSON: /api/errors/8f8330e7fdde7ace. Report an issue: GitHub.