mastra-ai/mastra · error

Model "${modelId}" is not available. Available models: ${ids

Error message

Model "${modelId}" is not available. Available models: ${ids}

What it means

The handler looks up the agent by id in the agents store; when getById returns null the endpoint responds 404 with this message. It is a plain resource-not-found signal, not an infrastructure fault.

Source

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

  }

  get sessionId(): string | undefined {
    return this.session?.sessionId;
  }

  async getAvailableModels(): Promise<ModelInfo[]> {
    await this.ensureConnected();
    return this.session?.models?.availableModels ?? [];
  }

  async setModel(modelId: string): Promise<void> {
    await this.ensureConnected();

    const available = this.session?.models?.availableModels;

    if (available && !available.some(m => m.modelId === modelId)) {
      const ids = available.map(m => m.modelId).join(', ') || '(none)';
      throw new Error(`Model "${modelId}" is not available. Available models: ${ids}`);
    }

    await this.connection!.unstable_setSessionModel({
      sessionId: this.session!.sessionId,
      modelId,
    });
  }

  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('');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the agentId exists via GET /api/agents (list) before calling version endpoints
2. Fix the path parameter value to the stored agent id
3. If the agent should exist, check you are connected to the intended storage (env DATABASE_URL etc.) and that data wasn't wiped/migrated
4. Re-register the agent in storage if the record was deleted

Example fix

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

const agents = await fetch('/api/agents').then(r => r.json());
if (!agents.some(a => a.id === agentId)) throw new Error(`Agent ${agentId} not present in storage`);

function agentExists(agents: {id: string}[], id: string): boolean {
  return agents.some(a => a.id === id);
}

try {
  await fetch(`/api/agents/${agentId}/versions/${versionId}`);
} catch (e) {
  if (isHttpError(e) && e.status === 404 && e.message.includes('Agent with id')) {
    // refresh agent list / fix path param
  } else throw e;
}

When it happens

Trigger: GET/POST /api/agents/:agentId/versions... where :agentId does not exist in storage, or the agent record was deleted before this call.

Common situations: Stale client caches holding agent ids from a wiped database; typos in the agentId path param; pointing a client at a different environment (staging DB) than the one that registered the agent; agents created only in code (new Agent(...)) but never registered in the agents store.

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

• ClaudeSDKAgent resumeData must include either sessionId or c
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo
• ClaudeSDKAgent resumeData.sessionId must be a string.
• ClaudeSDKAgent resumeData.continue must be true when provide

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