{"record":{"id":"be6a81b79d438513","repo":"CherryHQ/cherry-studio","slug":"cherry-assistant-package-configuration-is-invalid","errorCode":null,"errorMessage":"Cherry Assistant package configuration is invalid: ${invalidKeys.join(', ') || '<root>'}","messagePattern":"Cherry Assistant package configuration is invalid: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ai/agents/builtin/builtinAgentDefinition.ts","lineNumber":96,"sourceCode":"  } catch (error) {\n    logger.error('Failed to load builtin agent definition', {\n      builtinRole,\n      agentJsonPath,\n      error: error instanceof Error ? error.message : String(error)\n    })\n    return undefined\n  }\n}\n\nexport function loadBuiltinAssistantDefaults(language?: string): BuiltinAssistantDefaults {\n  const definition = loadBuiltinAgentDefinition('assistant', language)\n  if (!definition) {\n    throw new Error('Cherry Assistant package definition is unavailable')\n  }\n\n  const { data: configuration, invalidKeys } = sanitizeAgentConfiguration(definition.configuration)\n  if (!configuration || invalidKeys.length > 0) {\n    throw new Error(`Cherry Assistant package configuration is invalid: ${invalidKeys.join(', ') || '<root>'}`)\n  }\n\n  return {\n    name: definition.name?.trim() || 'Cherry Assistant',\n    configuration: { ...configuration, builtin_role: 'assistant' }\n  }\n}\n","sourceCodeStart":78,"sourceCodeEnd":104,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/agents/builtin/builtinAgentDefinition.ts#L78-L104","documentation":"Thrown by loadBuiltinAssistantDefaults when the assistant agent.json loaded successfully but sanitizeAgentConfiguration rejected its configuration — either it returned no data or it surfaced invalidKeys (configuration keys that do not match the known agent configuration schema). This protects downstream code from a builtin definition carrying unknown/renamed fields.","triggerScenarios":"loadBuiltinAssistantDefaults() runs and the assistant agent.json's `configuration` object contains keys not allowed by the agent configuration schema, or the whole configuration is null/empty when one is required.","commonSituations":"The builtin agent.json was hand-edited to add a non-schema key; a schema migration renamed/removed a key but the bundled template was not updated in lockstep; a stale template ships with a newer schema; a localization/merge tool injected stray fields.","solutions":["Read the error message: invalidKeys lists exactly which keys are rejected ('<root>' means the configuration object itself is missing/invalid).","Open the assistant agent.json and remove or rename the offending keys to match the current agent configuration schema.","Regenerate/restore the builtin template from source so it matches the schema version of the running app.","Keep builtin templates and the configuration schema in the same change unit so they do not drift."],"exampleFix":"// before: agent.json carries a removed key\n{ \"configuration\": { \"model_id\": \"x\", \"oldRenamedKey\": true } }\n\n// after: align with the current schema\n{ \"configuration\": { \"model_id\": \"x\", \"newKeyName\": true } }","handlingStrategy":"validation","validationCode":"import fs from 'node:fs'\nfunction assistantConfigIsValid(): boolean {\n  const dir = getBuiltinAgentTemplateDirectory('assistant')\n  if (!dir) return false\n  try {\n    const cfg = JSON.parse(fs.readFileSync(path.join(dir, 'agent.json'), 'utf-8')).configuration\n    const { invalidKeys } = sanitizeAgentConfiguration(cfg)\n    return invalidKeys.length === 0\n  } catch {\n    return false\n  }\n}\nif (!assistantConfigIsValid()) {\n  // surface 'builtin assistant configuration out of sync with schema' to the user\n}","typeGuard":"function hasInvalidKeys(r: { invalidKeys: string[] }): boolean {\n  return r.invalidKeys.length > 0\n}","tryCatchPattern":"try {\n  const defaults = loadBuiltinAssistantDefaults(language)\n} catch (e) {\n  if (e instanceof Error && /package configuration is invalid/.test(e.message)) {\n    // schema/template drift: rebuild templates from source to match schema\n    logger.error('Builtin assistant config failed schema validation', { error: e })\n  } else throw e\n}","preventionTips":["Change builtin templates and the configuration schema in the same commit.","Add a CI check that runs sanitizeAgentConfiguration over shipped templates.","Never hand-edit shipped builtin agent.json outside the schema."],"tags":["agents","schema","config","builtin","validation"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}