CherryHQ/cherry-studio · error · Error

Cherry Assistant package configuration is invalid: ${invalid

Error message

Cherry Assistant package configuration is invalid: ${invalidKeys.join(', ') || '<root>'}

What it means

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.

Source

Thrown at src/main/ai/agents/builtin/builtinAgentDefinition.ts:96

  } catch (error) {
    logger.error('Failed to load builtin agent definition', {
      builtinRole,
      agentJsonPath,
      error: error instanceof Error ? error.message : String(error)
    })
    return undefined
  }
}

export function loadBuiltinAssistantDefaults(language?: string): BuiltinAssistantDefaults {
  const definition = loadBuiltinAgentDefinition('assistant', language)
  if (!definition) {
    throw new Error('Cherry Assistant package definition is unavailable')
  }

  const { data: configuration, invalidKeys } = sanitizeAgentConfiguration(definition.configuration)
  if (!configuration || invalidKeys.length > 0) {
    throw new Error(`Cherry Assistant package configuration is invalid: ${invalidKeys.join(', ') || '<root>'}`)
  }

  return {
    name: definition.name?.trim() || 'Cherry Assistant',
    configuration: { ...configuration, builtin_role: 'assistant' }
  }
}

View on GitHub (pinned to 726446b54c)

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.

Example fix

// before: agent.json carries a removed key
{ "configuration": { "model_id": "x", "oldRenamedKey": true } }

// after: align with the current schema
{ "configuration": { "model_id": "x", "newKeyName": true } }

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs'
function assistantConfigIsValid(): boolean {
  const dir = getBuiltinAgentTemplateDirectory('assistant')
  if (!dir) return false
  try {
    const cfg = JSON.parse(fs.readFileSync(path.join(dir, 'agent.json'), 'utf-8')).configuration
    const { invalidKeys } = sanitizeAgentConfiguration(cfg)
    return invalidKeys.length === 0
  } catch {
    return false
  }
}
if (!assistantConfigIsValid()) {
  // surface 'builtin assistant configuration out of sync with schema' to the user
}

Type guard

function hasInvalidKeys(r: { invalidKeys: string[] }): boolean {
  return r.invalidKeys.length > 0
}

Try / catch

try {
  const defaults = loadBuiltinAssistantDefaults(language)
} catch (e) {
  if (e instanceof Error && /package configuration is invalid/.test(e.message)) {
    // schema/template drift: rebuild templates from source to match schema
    logger.error('Builtin assistant config failed schema validation', { error: e })
  } else throw e
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/be6a81b79d438513. Report an issue: GitHub.