mastra-ai/mastra · error · ApiCliError

REQUEST_TIMEOUT

REQUEST_TIMEOUT

Error message

REQUEST_TIMEOUT: Request timed out after ${options.timeoutMs}ms

What it means

requestApi wraps every fetch with an AbortController whose timer fires after options.timeoutMs. If the abort fires before the HTTP exchange completes, the fetch rejects with an AbortError, which requestApi converts into ApiCliError('REQUEST_TIMEOUT', ...). It exists so CLI callers get a consistent, typed error instead of a raw abort signal when the Mastra server is slow or unreachable in time.

Source

Thrown at packages/cli/src/commands/api/client.ts:46

    if (options.descriptor.method !== 'GET' && bodyInput) {
      init.headers = { 'content-type': 'application/json', ...init.headers };
      init.body = JSON.stringify(bodyInput);
    }

    const response = await fetch(url, init);
    const body = await parseResponse(response);

    if (!response.ok) {
      throw new ApiCliError('HTTP_ERROR', `Request failed with status ${response.status}`, {
        status: response.status,
        body,
      });
    }

    return body;
  } catch (error) {
    if (error instanceof Error && error.name === 'AbortError') {
      throw new ApiCliError('REQUEST_TIMEOUT', `Request timed out after ${options.timeoutMs}ms`, {
        timeoutMs: options.timeoutMs,
      });
    }
    throw toApiCliError(error);
  } finally {
    clearTimeout(timeout);
  }
}

export function buildUrl(
  baseUrl: string,
  path: string,
  pathParams: Record<string, string>,
  input?: Record<string, unknown>,
  apiPrefix?: string,
): string {
  const pathParamNames = new Set<string>();
  const resolvedPath = path.replace(/:([A-Za-z0-9_]+)/g, (_, name: string) => {

View on GitHub (pinned to 75dd419e61)

Solutions

Retry with a larger timeoutMs (check the reported value in the error details and raise it, e.g. 10000-60000ms).
Verify the Mastra server is running and reachable at the configured baseUrl (curl the endpoint manually) and check server logs for slowness.
If the endpoint is inherently slow, use a non-blocking health/schema check first, then call the slow endpoint with an adequate timeout.
For persistent slowness, investigate server-side: DB/storage latency, background tasks, or resource contention on the host.

Example fix

// before
await requestApi({ baseUrl, headers, timeoutMs: 1000, descriptor, pathParams });
// after
await requestApi({ baseUrl, headers, timeoutMs: 30000, descriptor, pathParams });

Defensive patterns

Strategy: retry

Validate before calling

// Optionally pre-check reachability before the real call
const ctrl = new AbortController();
const t = setTimeout(() => ctrl.abort(), 2000);
try {
  await fetch(new URL('/api', baseUrl), { signal: ctrl.signal });
} finally {
  clearTimeout(t);
}

Try / catch

try {
  await requestApi({ baseUrl, headers, timeoutMs, descriptor, pathParams });
} catch (e) {
  if (e instanceof ApiCliError && e.code === 'REQUEST_TIMEOUT') {
    // retry with backoff and/or a larger timeoutMs
  } else {
    throw e;
  }
}

Prevention

Set timeoutMs generously for heavy endpoints (schema fetches, agent runs); 1-2s is rarely enough.
Implement retry with exponential backoff for idempotent GET commands.
Verify the server health endpoint before long-running calls.
Surface the timeoutMs from error details in your own error messages so users know what to raise.

When it happens

Trigger: Calling requestApi (directly or via fetchSchemaManifest or executeDescriptor) where the fetch of baseUrl + descriptor path does not complete within options.timeoutMs — e.g. server hung, slow network, or a very small timeoutMs value.

Common situations: Pointing the CLI at a Mastra server that is overloaded, starting up, or behind a stalled proxy; setting --timeout / timeoutMs too low for heavy endpoints (large schema manifests, long agent generations); running against localhost while the dev server is paused in a debugger.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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