CherryHQ/cherry-studio · critical · Error

Cherry Assistant package definition is unavailable

Error message

Cherry Assistant package definition is unavailable

What it means

Thrown by loadBuiltinAssistantDefaults when loadBuiltinAgentDefinition('assistant', language) returns undefined. That helper returns undefined in three cases: the builtin template directory cannot be resolved, the assistant's agent.json does not exist at feature.agents.builtin/<template>/agent.json, or reading/parsing agent.json threw (invalid JSON or a malformed skills array). Because the Cherry Assistant is a required built-in, its definition being unavailable is treated as a fatal startup/packaging defect.

Source

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

      name: resolveLocalizedField(agentConfig.name, language),
      instructions: resolveLocalizedField(agentConfig.instructions, language),
      configuration: agentConfig.configuration,
      skills: agentConfig.skills
    }
  } 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

  1. Confirm the assistant template dir exists and contains agent.json: check application.getPath('feature.agents.builtin') and the 'assistant' template name.
  2. Rebuild/reinstall the app so packaging includes the builtin agent templates.
  3. Validate agent.json parses as JSON (e.g. `node -e "JSON.parse(require('fs').readFileSync(path,'utf8'))"`).
  4. Check the logs for the preceding 'Builtin agent definition not found' / 'Failed to load builtin agent definition' line, which names the exact path and parse error.

Example fix

// before: agent.json missing from packaged resources
feature.agents.builtin/assistant/   (no agent.json)

// after: ship the template
feature.agents.builtin/assistant/agent.json   // valid JSON with name/instructions/configuration
Defensive patterns

Strategy: try-catch

Validate before calling

import fs from 'node:fs'
import path from 'node:path'
function assistantDefinitionAvailable(): boolean {
  const dir = getBuiltinAgentTemplateDirectory('assistant')
  if (!dir) return false
  const p = path.join(dir, 'agent.json')
  if (!fs.existsSync(p)) return false
  try { JSON.parse(fs.readFileSync(p, 'utf-8')); return true } catch { return false }
}
if (!assistantDefinitionAvailable()) {
  // surface 'builtin assistant resources missing — reinstall' to the user
}

Type guard

function isBuiltinDefinition(d: unknown): d is { configuration: Record<string, unknown> } {
  return typeof d === 'object' && d !== null && 'configuration' in d
}

Try / catch

try {
  const defaults = loadBuiltinAssistantDefaults(language)
} catch (e) {
  if (e instanceof Error && /package definition is unavailable/.test(e.message)) {
    // fatal startup defect: rebuild/reinstall so builtin templates ship
    logger.error('Builtin assistant resources missing', { error: e })
  } else throw e
}

Prevention

When it happens

Trigger: loadBuiltinAssistantDefaults() is called at startup/provisioning time and the assistant agent.json is missing, unreadable, or contains invalid JSON under application.getPath('feature.agents.builtin').

Common situations: Development environment without built assets present; broken packaging/ASAR that omitted the builtin agent template; a custom build path where feature.agents.builtin points at the wrong place; the agent.json file got deleted or truncated on disk; a filesystem/permission error reading the file.

Related errors

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