google-gemini/gemini-cli · error · Error

PromptConfig must define either `systemPrompt` or `initialMe

Error message

PromptConfig must define either `systemPrompt` or `initialMessages`.

What it means

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.

Source

Thrown at packages/core/src/agents/local-executor.ts:1062

        if (text) {
          textResponse += text;
        }
      }
    }

    return { functionCalls, textResponse, modelToUse };
  }

  /** Initializes a `GeminiChat` instance for the agent run. */
  private async createChatObject(
    inputs: AgentInputs,
    tools: FunctionDeclaration[],
  ): Promise<GeminiChat> {
    const { promptConfig } = this.definition;

    if (!promptConfig.systemPrompt && !promptConfig.initialMessages) {
      throw new Error(
        'PromptConfig must define either `systemPrompt` or `initialMessages`.',
      );
    }

    const startHistory = this.applyTemplateToInitialMessages(
      promptConfig.initialMessages ?? [],
      inputs,
    );

    // Build system instruction from the templated prompt string.
    const systemInstruction = promptConfig.systemPrompt
      ? await this.buildSystemPrompt(inputs)
      : undefined;

    try {
      const chat = new GeminiChat(
        this.executionContext,
        systemInstruction,

View on GitHub (pinned to 5024443c72)

Solutions

1. Add a systemPrompt string to promptConfig, or an initialMessages array.
2. Validate the agent definition at load time (schema check) so this surfaces before execution.
3. If building definitions programmatically, assert promptConfig.systemPrompt || promptConfig.initialMessages before registering the agent.

Example fix

// before
const agent = {
  name: 'helper',
  promptConfig: {}
};

// after
const agent = {
  name: 'helper',
  promptConfig: { systemPrompt: 'You are a helpful assistant.' }
};

function assertPromptConfig(pc) {
  if (!pc || (!pc.systemPrompt && !pc.initialMessages))
    throw new Error('promptConfig must define systemPrompt or initialMessages');
}

function hasPrompt(pc) {
  return !!pc && (typeof pc.systemPrompt === 'string' && pc.systemPrompt.length > 0)
    || (Array.isArray(pc.initialMessages) && pc.initialMessages.length > 0);
}

When it happens

Trigger: Running a custom/local agent whose definition.promptConfig is {} or has only unrelated fields. createChatObject runs at the start of every agent run.

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

Related errors

• Invalid approval mode: ${rawApprovalMode}. Valid values are:
• Invalid telemetry configuration: ${err.message}.
• Invalid regex pattern in allowedExtensions setting: "${patte
• Invalid environment variable name: "${key}". Must contain on
• Invalid environment variable value for "${key}". Values cann

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/40d7af8b0fdcdf01. Report an issue: GitHub.