{"record":{"id":"40d7af8b0fdcdf01","repo":"google-gemini/gemini-cli","slug":"promptconfig-must-define-either-systemprompt-or","errorCode":null,"errorMessage":"PromptConfig must define either `systemPrompt` or `initialMessages`.","messagePattern":"PromptConfig must define either `systemPrompt` or `initialMessages`\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/agents/local-executor.ts","lineNumber":1062,"sourceCode":"\n        if (text) {\n          textResponse += text;\n        }\n      }\n    }\n\n    return { functionCalls, textResponse, modelToUse };\n  }\n\n  /** Initializes a `GeminiChat` instance for the agent run. */\n  private async createChatObject(\n    inputs: AgentInputs,\n    tools: FunctionDeclaration[],\n  ): Promise<GeminiChat> {\n    const { promptConfig } = this.definition;\n\n    if (!promptConfig.systemPrompt && !promptConfig.initialMessages) {\n      throw new Error(\n        'PromptConfig must define either `systemPrompt` or `initialMessages`.',\n      );\n    }\n\n    const startHistory = this.applyTemplateToInitialMessages(\n      promptConfig.initialMessages ?? [],\n      inputs,\n    );\n\n    // Build system instruction from the templated prompt string.\n    const systemInstruction = promptConfig.systemPrompt\n      ? await this.buildSystemPrompt(inputs)\n      : undefined;\n\n    try {\n      const chat = new GeminiChat(\n        this.executionContext,\n        systemInstruction,","sourceCodeStart":1044,"sourceCodeEnd":1080,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/core/src/agents/local-executor.ts#L1044-L1080","documentation":"Thrown by LocalAgentExecutor.createChatObject when the agent definition's promptConfig has neither systemPrompt nor initialMessages. The chat object cannot be constructed without at least one of these, so this is a hard validation of the agent definition.","triggerScenarios":"Running a custom/local agent whose definition.promptConfig is {} or has only unrelated fields. createChatObject runs at the start of every agent run.","commonSituations":"Hand-written agent definition missing the prompt block; promptConfig ref unset; a dynamically generated definition that forgot to seed a prompt; migration where the field was renamed.","solutions":["Add a systemPrompt string to promptConfig, or an initialMessages array.","Validate the agent definition at load time (schema check) so this surfaces before execution.","If building definitions programmatically, assert promptConfig.systemPrompt || promptConfig.initialMessages before registering the agent."],"exampleFix":"// before\nconst agent = {\n  name: 'helper',\n  promptConfig: {}\n};\n\n// after\nconst agent = {\n  name: 'helper',\n  promptConfig: { systemPrompt: 'You are a helpful assistant.' }\n};","handlingStrategy":"validation","validationCode":"function assertPromptConfig(pc) {\n  if (!pc || (!pc.systemPrompt && !pc.initialMessages))\n    throw new Error('promptConfig must define systemPrompt or initialMessages');\n}","typeGuard":"function hasPrompt(pc) {\n  return !!pc && (typeof pc.systemPrompt === 'string' && pc.systemPrompt.length > 0)\n    || (Array.isArray(pc.initialMessages) && pc.initialMessages.length > 0);\n}","tryCatchPattern":null,"preventionTips":["Always set systemPrompt or initialMessages on agent definitions.","Schema-validate agent definitions at registration time.","Unit-test promptConfig presence for custom agents."],"tags":["agents","config","validation","prompt"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}