mastra-ai/mastra · error · Error

Poll failed: ${err.detail || resp.statusText}

Error message

Poll failed: ${err.detail || resp.statusText}

What it means

Thrown by pollEnvironmentDeploy when a status-poll HTTP request to the deploy API returns a non-ok response. The CLI polls every 2 seconds for the deploy status; if any poll request fails (e.g. 500 or 401), it aborts polling and surfaces the server's `detail` message or the HTTP status text. This means the deploy status could not be determined, not necessarily that the deploy itself failed.

Source

Thrown at packages/cli/src/commands/deploy/index.ts:510

    while (Date.now() - start < maxWaitMs) {
      const resp = await fetch(url, {
        headers: {
          Authorization: `Bearer ${currentToken}`,
          'x-organization-id': orgId,
        },
      });

      if (resp.status === 401) {
        currentToken = await getToken();
        // Back off before retrying so a persistently-401 token cannot spin
        // the poll loop into a tight retry storm against the platform API.
        await new Promise(r => setTimeout(r, 2000));
        continue;
      }

      if (!resp.ok) {
        const err = (await resp.json().catch(() => ({}))) as { detail?: string };
        throw new Error(`Poll failed: ${err.detail || resp.statusText}`);
      }

      const { deploy } = (await resp.json()) as { deploy: UnifiedDeployStatus };

      if (deploy.status === 'running' || deploy.status === 'failed' || deploy.status === 'stopped') {
        return deploy;
      }

      await new Promise(r => setTimeout(r, 2000));
    }

    throw new Error('Deploy timed out');
  } finally {
    logAbort.abort();
  }
}

/* ------------------------------------------------------------------ */

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Check the detail message in the error to see the exact API failure reason (auth, rate limit, server error).
  2. If it is a 401/403, regenerate the API token and re-export MASTRA_API_TOKEN, then retry the deploy.
  3. For transient 5xx/429, wait and re-run `mastra deploy`; poll failures are not necessarily fatal to the remote deploy.
  4. Verify network/proxy settings allow sustained access to the Mastra API for the duration of the deploy.

Example fix

// before: retries never handled, any failed poll aborts
throw new Error(`Poll failed: ${err.detail || resp.statusText}`);
// after: tolerate transient poll failures with a bounded retry
if (!resp.ok && resp.status >= 500 && transientFailures < 3) {
  transientFailures++;
  await new Promise(r => setTimeout(r, 2000));
  continue;
}
throw new Error(`Poll failed: ${err.detail || resp.statusText}`);
Defensive patterns

Strategy: retry

Validate before calling

// preflight the token before deploying
curl -s -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $MASTRA_API_TOKEN" https://api.mastra.ai/...

Try / catch

try {
  await deployAndPoll();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Poll failed:')) {
    // inspect detail, optionally retry with backoff
    console.error('Deploy status polling failed:', e.message);
  } else throw e;
}

Prevention

When it happens

Trigger: An intermediate poll response has resp.ok === false (any non-2xx status). The error message contains err.detail parsed from the response JSON body, or resp.statusText if the body has no detail field.

Common situations: Expired or revoked MASTRA_API_TOKEN mid-deploy (401); transient server 5xx during a long-running deploy poll; API gateway timeouts or rate limiting (429); network proxy interruptions returning HTML error pages.

Related errors

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