mastra-ai/mastra · error · HTTPException

Connection ${connectionId} not found for provider ${provider

Error message

Connection ${connectionId} not found for provider ${providerId}

What it means

A 404 thrown when no connection row with the given connectionId exists for the provider, after listing connections by the caller's author. The server looks up rows scoped to the provider and the caller's authorship; a mismatched or nonexistent ID yields this error.

Source

Thrown at packages/server/src/server/handlers/tool-providers.ts:693

  handler: async ({ mastra, providerId, connectionId, label, requestContext }) => {
    try {
      const editor = requireEditor(mastra.getEditor());
      const provider = await resolveProvider(editor, providerId);
      const callerAuthorId = resolveOwnerId(requestContext, mastra.getLogger());
      const isAdmin = requestContext ? hasAdminBypass(requestContext, TOOL_PROVIDERS_RESOURCE) : false;

      const storage = mastra.getStorage();
      const store = await storage?.getStore('toolProviderConnections');
      if (!store) {
        throw new HTTPException(500, {
          message: 'Tool provider connections storage is not configured',
        });
      }

      const rows = await store.listConnectionsByAuthor({ providerId: provider.info.id });
      const match = rows.find(r => r.connectionId === connectionId);
      if (!match) {
        throw new HTTPException(404, {
          message: `Connection ${connectionId} not found for provider ${providerId}`,
        });
      }

      const isShared = match.scope === 'shared';
      if (!isShared && match.authorId !== callerAuthorId && !isAdmin) {
        throw new HTTPException(403, {
          message: 'You do not have permission to update this connection',
        });
      }

      // Normalize: empty string and explicit null both clear the label.
      const nextLabel: string | null = typeof label === 'string' && label.trim().length > 0 ? label.trim() : null;

      await store.upsertConnection({
        authorId: match.authorId,
        providerId: provider.info.id,
        toolkit: match.toolkit,

View on GitHub (pinned to 75dd419e61)

Solutions

Verify connectionId and providerId are correct; list connections for the provider first.
If the connection belongs to another author, act as an admin or use the shared-scope connection's ID.
Recreate the connection if it was deleted, and use the new connectionId.

Example fix

// before
await api.get(`/api/tool-providers/github/connections/conn_123`);
// after
const { connections } = await api.get(`/api/tool-providers/github/connections`);
const target = connections.find(c => c.label === 'my-github');
await api.get(`/api/tool-providers/github/connections/${target.connectionId}`);

Defensive patterns

Strategy: validation

Validate before calling

const list = await api.get(`/api/tool-providers/${providerId}/connections`);
if (!list.connections.some(c => c.connectionId === connectionId)) {
  throw new Error(`Unknown connectionId ${connectionId} for provider ${providerId}`);
}

Try / catch

try {
  await api.get(`/api/tool-providers/${p}/connections/${id}`);
} catch (e) {
  if (e.status === 404) {
    const { connections } = await api.get(`/api/tool-providers/${p}/connections`);
    // refresh local cache of valid connection IDs
  } else throw e;
}

Prevention

Fetch and cache connection IDs from the list endpoint instead of hardcoding.
Verify scope/author of connections you reference across users.
Refresh stored connection IDs after deletes/recreations.

When it happens

Trigger: GET/PUT/DELETE on a connection whose connectionId was never created, belongs to a different providerId, or is scoped to another author so it isn't in listConnectionsByAuthor results for the caller.

Common situations: Typo'd or stale connectionId from a previous environment; connection created under a different author (personal scope) so the caller's listing omits it; using a connectionId from a different provider.

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

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