{"record":{"id":"ee3039f82ba91616","repo":"actualbudget/actual","slug":"invalid-config-file-unknown-key-key","errorCode":null,"errorMessage":"Invalid config file: unknown key \"${key}\"","messagePattern":"Invalid config file: unknown key \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/config.ts","lineNumber":78,"sourceCode":"  noLock?: boolean;\n};\n\nconst configFileKeys: readonly string[] = [\n  ...stringKeys,\n  ...numberKeys,\n  ...booleanKeys,\n];\n\nfunction validateConfigFileContent(value: unknown): ConfigFileContent {\n  if (!isRecord(value)) {\n    throw new Error(\n      'Invalid config file: expected an object with keys: ' +\n        configFileKeys.join(', '),\n    );\n  }\n  for (const key of Object.keys(value)) {\n    if (!configFileKeys.includes(key)) {\n      throw new Error(`Invalid config file: unknown key \"${key}\"`);\n    }\n    const v = value[key];\n    if (v === undefined) continue;\n    if (\n      (stringKeys as readonly string[]).includes(key) &&\n      typeof v !== 'string'\n    ) {\n      throw new Error(\n        `Invalid config file: key \"${key}\" must be a string, got ${typeof v}`,\n      );\n    }\n    if (\n      (numberKeys as readonly string[]).includes(key) &&\n      (typeof v !== 'number' || !Number.isInteger(v) || v < 0)\n    ) {\n      throw new Error(\n        `Invalid config file: key \"${key}\" must be a non-negative integer`,\n      );","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/actualbudget/actual/blob/d4334cb6e6123f4d3bcea1ad6166608884c7e658/packages/cli/src/config.ts#L60-L96","documentation":"When validating the CLI config file, every key present must be one of the recognized option names (serverUrl, password, sessionToken, syncId, dataDir, encryptionPassword, cacheTtl, lockTimeout, noLock). Any unknown key causes this error, so typos and renamed options are caught immediately instead of being silently ignored.","triggerScenarios":"A config file containing `syncId` misspelled as `syncID` or `sync-id`; leftover keys from an older CLI version (e.g. removed options); keys meant for the sync-server config (like `serverFiles` or `port`) placed in the CLI config; camelCase mistakes such as `serverurl` or `data-dir`.","commonSituations":"Merging server config examples into the CLI config; upgrading/downgrading and carrying deprecated keys; documentation drift between versions.","solutions":["Remove or rename the offending key to one of: serverUrl, password, sessionToken, syncId, dataDir, encryptionPassword, cacheTtl, lockTimeout, noLock","Check the error message — it names the exact unknown key; fix its casing/spelling","If the option belongs to the sync-server, move it to the server's own config file","Consult the CLI docs for your installed version to see current valid keys"],"exampleFix":"// before (actual.config.json)\n{ \"serverurl\": \"http://localhost:5006\", \"dataDir\": \"./data\" }\n\n// after\n{ \"serverUrl\": \"http://localhost:5006\", \"dataDir\": \"./data\" }","handlingStrategy":"validation","validationCode":"const ALLOWED = ['serverUrl','password','sessionToken','syncId','dataDir','encryptionPassword','cacheTtl','lockTimeout','noLock'];\nfor (const k of Object.keys(cfg)) {\n  if (!ALLOWED.includes(k)) throw new Error(`Unknown CLI config key \"${k}\"`);\n}","typeGuard":"function onlyKnownKeys(v: Record<string, unknown>, allowed: readonly string[]): boolean {\n  return Object.keys(v).every(k => allowed.includes(k));\n}","tryCatchPattern":"try {\n  await run(['actual', 'accounts']);\n} catch (e) {\n  if (String(e.message).includes('unknown key')) {\n    const key = /unknown key \"(.+?)\"/.exec(String(e.message))?.[1];\n    console.error(`Remove or rename \"${key}\" in your config file`);\n  } else throw e;\n}","preventionTips":["Type keys exactly as documented: camelCase, e.g. serverUrl not serverurl or server-url","Diff your config against the key list in the error message after CLI upgrades","Keep server-only options out of the CLI config file"],"tags":["cli","config","validation","unknown-key"],"backgroundTag":"invalid-config-file","analyzedSha":"d4334cb6e6123f4d3bcea1ad6166608884c7e658","analyzedAt":"2026-08-29T01:02:11.213Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}