mastra-ai/mastra · error

ACP connection is not initialized

Error message

ACP connection is not initialized

What it means

After the agent is found, the handler fetches the stored version record by versionId; a null result yields a 404 with this message. The version row simply does not exist in the agents store.

Source

Thrown at agent-sdks/acp/src/connection.ts:155

  async prompt(task: string, signal?: AbortSignal): Promise<string> {
    const parts: string[] = [];

    for await (const event of this.promptStream(task, signal)) {
      if (event.type === 'text') {
        parts.push(event.text);
      }
    }

    return parts.join('');
  }

  async *promptStream(task: string, signal?: AbortSignal): AsyncGenerator<ACPStreamEvent> {
    await this.ensureConnected();

    const sessionId = this.session?.sessionId;

    if (!this.connection || !sessionId) {
      throw new Error('ACP connection is not initialized');
    }

    if (signal?.aborted) {
      await this.cancel();
      throw signal.reason ?? new Error('ACP prompt aborted');
    }

    const queue = createAsyncQueue<ACPStreamEvent>();
    const state: PromptState = {
      sessionId,
      onEvent: event => queue.push(event),
    };
    this.currentPrompt = state;

    const abortHandler = () => {
      void this.cancel();
      queue.throw(signal?.reason ?? new Error('ACP prompt aborted'));
    };

View on GitHub (pinned to 75dd419e61)

Solutions

1. List available versions via GET /api/agents/:agentId/versions and use a valid versionId
2. Fix the versionId path parameter (check casing/format)
3. Connect the server to the storage environment that actually holds the version
4. Restore the version data from backup if it was deleted unintentionally

Example fix

// before
await fetch(`/api/agents/${agentId}/versions/${versionId}`);
// after
const versions = await fetch(`/api/agents/${agentId}/versions`).then(r => r.json());
const valid = versions.find(v => v.id === versionId);
if (valid) await fetch(`/api/agents/${agentId}/versions/${versionId}`);

const versions = await fetch(`/api/agents/${agentId}/versions`).then(r => r.json());
if (!versions.some(v => v.id === versionId)) throw new Error(`Version ${versionId} does not exist for ${agentId}`);

function versionExists(versions: {id: string}[], id: string): boolean {
  return versions.some(v => v.id === id);
}

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}`);
} catch (e) {
  if (isHttpError(e) && e.status === 404 && e.message.startsWith('Version with id')) {
    // refetch version list and pick a valid id
  } else throw e;
}

When it happens

Trigger: GET/POST /api/agents/:agentId/versions/:versionId where :versionId was never created, was pruned, or belongs to a different storage backend.

Common situations: Reusing a versionId copied from logs of another environment; databases reset between test runs; retention/cleanup jobs deleting old versions; calling before any version snapshot has been persisted.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData.sessionId must be a string.
• ClaudeSDKAgent resumeData.continue must be true when provide
• Version with id ${from} not found
• Version with id ${to} not found

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/fe3ed01ac51e7817. Report an issue: GitHub.