mastra-ai/mastra · error · PlatformApiError

Failed to fetch connection string — ${await extractError(res

Error message

Failed to fetch connection string — ${await extractError(res)}

What it means

getDatabaseConnection calls GET /v1/server/projects/:id/databases/:dbId/connection, which only returns 200 once the database is `ready`. Any non-ok response becomes this PlatformApiError with the upstream status and the server's error text.

Source

Thrown at mastracode/mastra-factory/src/platform.ts:198

/** GET /v1/server/projects/:id/databases/:dbId/connection — only 200s when `ready`. */
export async function getDatabaseConnection({
  token,
  orgId,
  projectId,
  databaseId,
}: {
  token: string;
  orgId: string;
  projectId: string;
  databaseId: string;
}): Promise<DatabaseConnection> {
  const res = await platformFetch(
    `${MASTRA_PLATFORM_API_URL}/v1/server/projects/${encodeURIComponent(projectId)}/databases/${encodeURIComponent(databaseId)}/connection`,
    { headers: authHeaders(token, orgId) },
  );
  if (!res.ok) {
    throw new PlatformApiError(res.status, `Failed to fetch connection string — ${await extractError(res)}`);
  }
  return (await res.json()) as DatabaseConnection;
}

/**
 * Poll `getDatabaseStatus` until the database is `ready`.
 *
 * Each poll is bounded by the *remaining* overall budget via a per-request
 * `AbortSignal`, so a hung `platformFetch` can't blow past `timeoutMs`. When
 * an outer `signal` is supplied it composes with the per-request timeout —
 * whichever fires first aborts the in-flight request.
 *
 * @param intervalMs how often to poll (default 2s)
 * @param timeoutMs total budget (default 60s)
 */
export async function waitForDatabaseReady({
  token,
  orgId,

View on GitHub (pinned to 75dd419e61)

Solutions

Always await waitForDatabaseReady (status === 'ready') before fetching the connection string.
Re-authenticate if the token has expired, then retry the connection fetch.
Verify projectId/databaseId match the attached database for the given org.
Retry after a short delay if the status indicates the database is still transitioning.

Example fix

// before
const conn = await getDatabaseConnection({ token, orgId, projectId, databaseId });
// after
await waitForDatabaseReady({ token, orgId, projectId, databaseId });
const conn = await getDatabaseConnection({ token, orgId, projectId, databaseId });

Defensive patterns

Strategy: validation

Validate before calling

// only fetch connection after the DB reports ready
const db = await waitForDatabaseReady({ token, orgId, projectId, databaseId });
if (db.status !== 'ready') throw new Error(`Database not ready (${db.status}); cannot fetch connection yet.`);
const conn = await getDatabaseConnection({ token, orgId, projectId, databaseId });

Type guard

function isReady(db) { return db?.status === 'ready'; }

Try / catch

try {
  return await getDatabaseConnection(opts);
} catch (err) {
  if (err instanceof PlatformApiError && (err.status === 404 || err.status === 409)) {
    // DB not ready yet — wait then retry once
    await waitForDatabaseReady(opts);
    return getDatabaseConnection(opts);
  }
  throw err;
}

Prevention

Always gate the connection fetch behind a successful waitForDatabaseReady.
Re-authenticate if scripts run longer than token lifetime.
Verify projectId/databaseId against the attach response rather than hand-copying.
Serialize provisioning steps; avoid concurrent CLI runs on the same database.

When it happens

Trigger: Fetching the connection string before the database is ready (409/425-style response or 404), with an expired/invalid token (401), wrong ids (404), or a platform-side failure (5xx).

Common situations: Calling `connection` immediately after creation without waiting for `ready` status; stale token in a long script; copying the wrong databaseId; racing two CLI runs against the same database.

Related errors

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