google-gemini/gemini-cli · error · Error

Remote agent '${definition.name}' requires a string 'query'

Error message

Remote agent '${definition.name}' requires a string 'query' input.

What it means

Thrown in the RemoteAgentInvocation constructor when params['query'] is present but not a string. Note the fallback `params['query'] ?? DEFAULT_QUERY_STRING` means a missing query uses the default 'Get Started!' and does NOT throw; only an explicitly non-string query (number, object, array, boolean) triggers this.

Source

Thrown at packages/core/src/agents/remote-invocation.ts:68

  >();
  // State for the ongoing conversation with the remote agent
  private contextId: string | undefined;
  private taskId: string | undefined;

  private readonly clientManager: A2AClientManager;
  private authHandler: AuthenticationHandler | undefined;

  constructor(
    private readonly definition: RemoteAgentDefinition,
    private readonly context: AgentLoopContext,
    params: AgentInputs,
    messageBus: MessageBus,
    _toolName?: string,
    _toolDisplayName?: string,
  ) {
    const query = params['query'] ?? DEFAULT_QUERY_STRING;
    if (typeof query !== 'string') {
      throw new Error(
        `Remote agent '${definition.name}' requires a string 'query' input.`,
      );
    }
    // Safe to pass strict object to super
    super(
      { query },
      messageBus,
      _toolName ?? definition.name,
      _toolDisplayName ?? definition.displayName,
    );
    const clientManager = this.context.config.getA2AClientManager();
    if (!clientManager) {
      throw new Error(
        `Failed to initialize RemoteAgentInvocation for '${definition.name}': A2AClientManager is not available.`,
      );
    }
    this.clientManager = clientManager;
  }

View on GitHub (pinned to 5024443c72)

Solutions

1. Ensure the caller passes query as a string: String(params.query) or a typed check before construction.
2. If the query is optional, omit the key rather than passing a non-string.
3. Type the params at the call site with RemoteAgentInputs / { query: string }.

Example fix

// before
new RemoteAgentInvocation(def, ctx, { query: 42 }, bus);

// after
new RemoteAgentInvocation(def, ctx, { query: 'Summarize the report' }, bus);

function normalizeQuery(params) {
  const q = params['query'] ?? 'Get Started!';
  if (typeof q !== 'string') throw new Error('query must be a string');
  return { query: q };
}

function isStringQuery(params) {
  const q = params['query'];
  return q === undefined || typeof q === 'string';
}

When it happens

Trigger: Constructing RemoteAgentInvocation with params = { query: 123 } or { query: {...} } or { query: true }. Omitting query is safe (default applies).

Common situations: Tool-dispatch layer passing a structured object or number as query instead of a string; a serialized JSON payload where query was parsed as a non-string scalar; programmatic misuse of the invocation class.

Related errors

• Remote agent '${definition.name}' requires a string 'query'
• Failed to create auth provider for agent '${definition.name}
• Failed to initialize RemoteAgentInvocation for '${definition
• Failed to create auth provider for agent '${definition.name}
• PromptConfig must define either `systemPrompt` or `initialMe

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