mastra-ai/mastra · error

xAI device authorization response missing required fields

Error message

xAI device authorization response missing required fields

What it means

After a successful (2xx) device-authorization call, startXAIDeviceLogin requires device_code, user_code, and verification_uri to be present. If any is missing from the JSON body, the response cannot drive the device flow and this error is thrown.

Source

Thrown at mastracode/sdk/src/auth/providers/xai.ts:119

export async function startXAIDeviceLogin(options?: { signal?: AbortSignal }): Promise<XAIDeviceLoginPending> {
  const response = await postForm(DEVICE_CODE_URL, { client_id: CLIENT_ID, scope: SCOPE }, options?.signal);

  if (!response.ok) {
    const text = await response.text().catch(() => '');
    throw new Error(`Failed to initiate xAI device authorization: ${response.status}${text ? ` ${text}` : ''}`);
  }

  const data = (await response.json()) as {
    device_code?: string;
    user_code?: string;
    verification_uri?: string;
    verification_uri_complete?: string;
    interval?: number;
    expires_in?: number;
  };

  if (!data.device_code || !data.user_code || !data.verification_uri) {
    throw new Error('xAI device authorization response missing required fields');
  }

  const url = validateVerificationUri(data.verification_uri_complete ?? data.verification_uri);

  return {
    deviceCode: data.device_code,
    userCode: data.user_code,
    url,
    instructions: `Enter code: ${data.user_code}`,
    state: createDeviceCodePollState({
      intervalSeconds: data.interval,
      expiresInSeconds: typeof data.expires_in === 'number' && data.expires_in > 0 ? data.expires_in : 600,
    }),
  };
}

async function pollXAITokenOnce(
  pending: XAIDeviceLoginPending,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Log the raw 2xx response body to see which fields are missing.
2. Confirm the device-code endpoint URL is the official xAI one, not an overridden or mocked URL.
3. Bypass intercepting proxies/captive portals for xAI API hosts.
4. Retry; if persistent, check for a provider API change and upgrade the SDK.

function isCompleteDeviceAuthResponse(b: unknown): b is { device_code: string; user_code: string; verification_uri: string } {
  const r = (b ?? {}) as Record<string, unknown>;
  return typeof r.device_code === 'string' && r.device_code.length > 0
    && typeof r.user_code === 'string' && r.user_code.length > 0
    && typeof r.verification_uri === 'string' && r.verification_uri.length > 0;
}

function hasRequiredDeviceFields(data: unknown): data is { device_code: string; user_code: string; verification_uri: string } {
  const r = (data ?? {}) as Record<string, unknown>;
  return Boolean(r.device_code) && Boolean(r.user_code) && Boolean(r.verification_uri);
}

try {
  pending = await startXAIDeviceLogin();
} catch (e) {
  if (e instanceof Error && e.message.includes('missing required fields')) {
    // 2xx but wrong body: log raw body, check endpoint/proxy, then retry
    restartDeviceFlow();
  }
}

When it happens

Trigger: postForm to DEVICE_CODE_URL returns 2xx but the parsed JSON lacks one of device_code, user_code, or verification_uri.

Common situations: A gateway/proxy returns a 2xx with an unexpected body (e.g. login page or empty JSON); xAI API contract change; pointing DEVICE_CODE_URL at a wrong endpoint that still answers 200.

Related errors

• xAI device authorization returned an invalid verification_ur
• xAI device authorization returned a non-https verification_u
• xAI token response missing access_token
• xAI token response missing refresh_token
• Failed to initiate xAI device authorization: ${response.stat

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