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

After parsing the Paperclip config JSON, findPaperclipConfigKeyWarnings flags unrecognized keys that closely resemble known keys and prints a did-you-mean suggestion. The unknown key is preserved passthrough rather than dropped — but it has no effect until renamed, so the intended setting is silently inert.

Source

Thrown at server/src/config-file.ts:35

}

export function readConfigFile(): PaperclipConfig | null {
  const configPath = resolvePaperclipConfigPath();

  if (!fs.existsSync(configPath)) return null;

  let raw: unknown;
  try {
    raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
  } catch (error) {
    const reason = error instanceof Error ? error.message : String(error);
    throw new Error(`Invalid Paperclip config at ${configPath}: failed to read or parse JSON: ${reason}`);
  }

  try {
    const config = paperclipConfigSchema.parse(raw);
    for (const warning of findPaperclipConfigKeyWarnings(config)) {
      console.warn(
        `Unknown config key ${warning.path}; did you mean ${warning.suggestion}? It will be preserved.`,
      );
    }
    return config;
  } catch (error) {
    if (error instanceof ZodError) {
      throw new Error(`Invalid Paperclip config at ${configPath}: ${formatConfigValidationError(error)}`);
    }

    throw error;
  }
}

View on GitHub (pinned to 120ae5428f)

Solutions

Rename the key to the warning's suggestion in the config file.
If the key is obsolete after an upgrade, delete it.
Cross-check against the current config schema/docs for the exact valid key name.
Add a config-lint step in CI that fails on any unknown-key warning.

Example fix

// paperclip.config.json — before
{ "databseMode": "postgres" }

// after
{ "databaseMode": "postgres" }

Defensive patterns

Strategy: validation

Validate before calling

// Pre-deploy config gate: fail on any did-you-mean warning.
const config = loadPaperclipConfig(configPath);
const warnings = findPaperclipConfigKeyWarnings(config);
if (warnings.length > 0) {
  throw new Error(`Unknown config keys: ${warnings.map((w) => `${w.path} -> ${w.suggestion}`).join('; ')}`);
}

Prevention

Keep config files in version control and review them like code.
Run schema validation with unknown-key detection in CI, failing builds on typos.
Read release notes for config key renames before upgrading.
Remember the unknown key is preserved but inert — the setting you think you set is not set.

When it happens

Trigger: A config file contains a mistyped or renamed key that fuzzy-matches a valid one, e.g. a casing slip or a key renamed across Paperclip versions.

Common situations: Copy-pasting config from old docs or blog posts; upgrading Paperclip versions that renamed settings; hand-editing JSON and introducing typos; team members guessing key names.

Related errors

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