{"record":{"id":"6572fb39e3bf105b","repo":"CherryHQ/cherry-studio","slug":"cherry-assistant-package-definition-is-unavailable","errorCode":null,"errorMessage":"Cherry Assistant package definition is unavailable","messagePattern":"Cherry Assistant package definition is unavailable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/main/ai/agents/builtin/builtinAgentDefinition.ts","lineNumber":91,"sourceCode":"      name: resolveLocalizedField(agentConfig.name, language),\n      instructions: resolveLocalizedField(agentConfig.instructions, language),\n      configuration: agentConfig.configuration,\n      skills: agentConfig.skills\n    }\n  } 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":73,"sourceCodeEnd":104,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/agents/builtin/builtinAgentDefinition.ts#L73-L104","documentation":"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.","triggerScenarios":"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').","commonSituations":"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.","solutions":["Confirm the assistant template dir exists and contains agent.json: check application.getPath('feature.agents.builtin') and the 'assistant' template name.","Rebuild/reinstall the app so packaging includes the builtin agent templates.","Validate agent.json parses as JSON (e.g. `node -e \"JSON.parse(require('fs').readFileSync(path,'utf8'))\"`).","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."],"exampleFix":"// before: agent.json missing from packaged resources\nfeature.agents.builtin/assistant/   (no agent.json)\n\n// after: ship the template\nfeature.agents.builtin/assistant/agent.json   // valid JSON with name/instructions/configuration","handlingStrategy":"try-catch","validationCode":"import fs from 'node:fs'\nimport path from 'node:path'\nfunction assistantDefinitionAvailable(): boolean {\n  const dir = getBuiltinAgentTemplateDirectory('assistant')\n  if (!dir) return false\n  const p = path.join(dir, 'agent.json')\n  if (!fs.existsSync(p)) return false\n  try { JSON.parse(fs.readFileSync(p, 'utf-8')); return true } catch { return false }\n}\nif (!assistantDefinitionAvailable()) {\n  // surface 'builtin assistant resources missing — reinstall' to the user\n}","typeGuard":"function isBuiltinDefinition(d: unknown): d is { configuration: Record<string, unknown> } {\n  return typeof d === 'object' && d !== null && 'configuration' in d\n}","tryCatchPattern":"try {\n  const defaults = loadBuiltinAssistantDefaults(language)\n} catch (e) {\n  if (e instanceof Error && /package definition is unavailable/.test(e.message)) {\n    // fatal startup defect: rebuild/reinstall so builtin templates ship\n    logger.error('Builtin assistant resources missing', { error: e })\n  } else throw e\n}","preventionTips":["Ensure packaging/ASAR includes the builtin agent templates.","Validate agent.json presence and JSON validity in CI.","Keep feature.agents.builtin path resolution correct across platforms."],"tags":["agents","packaging","startup","builtin","config"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}