google-gemini/gemini-cli · critical · Error

Failed to initialize RemoteSessionInvocation for '${definiti

Error message

Failed to initialize RemoteSessionInvocation for '${definition.name}': A2AClientManager is not available.

What it means

Thrown by the RemoteSessionInvocation constructor when config.getA2AClientManager() returns undefined at construction time. The A2AClientManager is the central factory that creates and caches A2A protocol clients for remote agents; without it, the invocation has no transport layer and cannot stream messages to or from a remote agent endpoint. This is a fail-fast guard: the class refuses to instantiate rather than failing later during execute().

Source

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

  ) {
    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.`,
      );
    }
  }

  getDescription(): string {
    return `Calling remote agent ${this.definition.displayName ?? this.definition.name}`;
  }

  protected override async getConfirmationDetails(
    _abortSignal: AbortSignal,
  ): Promise<ToolCallConfirmationDetails | false> {
    return {
      type: 'info',
      title: `Call Remote Agent: ${this.definition.displayName ?? this.definition.name}`,
      prompt: `Calling remote agent: "${this.params.query}"`,
      onConfirm: async (_outcome: ToolConfirmationOutcome) => {
        // Policy updates are now handled centrally by the scheduler

View on GitHub (pinned to 5024443c72)

Solutions

Ensure remote agents are registered in settings.json or via the agent registry before any RemoteSessionInvocation is constructed, so Config initializes a2aClientManager.
If constructing invocations manually (e.g., in tests), provide a config whose getA2AClientManager() returns a real or mock A2AClientManager instance.
Verify that the AgentLoopContext passed to the constructor shares the same fully-initialized Config instance used by the rest of the application.
Check that any async initialization that populates a2aClientManager has been awaited before the tool call path executes.

Example fix

// before (config not initialized)
const invocation = new RemoteSessionInvocation(def, ctx, params, bus);

// after (ensure manager is present first)
if (!ctx.config.getA2AClientManager()) {
  throw new Error('Initialize A2A subsystem before invoking remote agents');
}
const invocation = new RemoteSessionInvocation(def, ctx, params, bus);

Defensive patterns

Strategy: validation

Validate before calling

// Before constructing RemoteSessionInvocation, verify the manager exists
const clientManager = context.config.getA2AClientManager();
if (!clientManager) {
  throw new Error(
    `Cannot invoke remote agent '${definition.name}': A2A client manager is not initialized. ` +
    `Register remote agents or ensure the A2A subsystem has started.`
  );
}

Type guard

// Type guard for a usable agent loop context for remote sessions
function hasA2AClientManager(
  ctx: AgentLoopContext
): ctx is AgentLoopContext & { config: Config & { getA2AClientManager(): NonNullable<ReturnType<Config['getA2AClientManager']>> } } {
  return ctx.config.getA2AClientManager() != null;
}

Try / catch

try {
  const invocation = new RemoteSessionInvocation(def, ctx, params, bus, opts);
} catch (e) {
  if (e instanceof Error && e.message.includes('A2AClientManager is not available')) {
    // Surface a user-friendly error, retry after init, or skip the agent
    return { error: 'Remote agent subsystem not ready. Please retry.' };
  }
  throw e;
}

Prevention

Always register remote agents before constructing invocations.
In tests, always mock getA2AClientManager to return a non-undefined value.
Centralize invocation construction in the registry so the guard is checked once.
Log a warning during startup if a2aClientManager is undefined but remote agents are configured.

When it happens

Trigger: Constructing a new RemoteSessionInvocation(definition, context, params, messageBus, options) where context.config.getA2AClientManager() returns undefined. This happens when the Config object's a2aClientManager field was never populated — typically because no remote agents were registered during startup, or the AgentLoopContext was built from a partial/mock config.

Common situations: Running remote agent tool calls before the agent registry has initialized the A2A subsystem; using a Config instance in tests that does not wire up a2aClientManager; upgrading to a version where A2AClientManager initialization moved to an async startup phase that hasn't completed; calling the invocation constructor directly instead of going through the registry's tool factory.

Related errors

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