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 RemoteSessionInvocation constructor (the session-based variant) when params['query'] is present but not a string. Identical semantics to error 214: a missing query falls back to DEFAULT_QUERY_STRING ('Get Started!') and does NOT throw; only an explicitly non-string value does.

Source

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

   * Format: `name::targetUrl` (or just `name` if no URL can be derived).
   */
  private static sessionKey(definition: RemoteAgentDefinition): string {
    const url = getRemoteAgentTargetUrl(definition);
    return url ? `${definition.name}::${url}` : definition.name;
  }

  private readonly _onAgentEvent?: (event: AgentEvent) => void;

  constructor(
    private readonly definition: RemoteAgentDefinition,
    private readonly context: AgentLoopContext,
    params: AgentInputs,
    messageBus: MessageBus,
    options?: SubagentInvocationOptions,
  ) {
    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,
      options?.toolName ?? definition.name,
      options?.toolDisplayName ?? definition.displayName,
    );
    this._onAgentEvent = options?.onAgentEvent;

    // Validate that A2AClientManager is available at construction time
    if (!this.context.config.getA2AClientManager()) {
      throw new Error(
        `Failed to initialize RemoteSessionInvocation for '${definition.name}': A2AClientManager is not available.`,
      );
    }

View on GitHub (pinned to 5024443c72)

Solutions

1. Pass query as a string from the caller.
2. Coerce or validate before construction: typeof params.query === 'string'.
3. If query is optional, omit the key so the default applies.

Example fix

// before
new RemoteSessionInvocation(def, ctx, { query: { text: 'hi' } }, bus, opts);

// after
new RemoteSessionInvocation(def, ctx, { query: 'hi' }, bus, opts);

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 RemoteSessionInvocation with params.query of a non-string type (number, object, array, boolean). The check runs in the constructor before super(...).

Common situations: Caller passes a structured object or non-string scalar as the query; a serialization layer parsed query into a number; programmatic misuse; mismatched param schema at the dispatch boundary.

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/d294858796781cee. Report an issue: GitHub.