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.

Solutions

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

Defensive patterns

Strategy: type-guard

Validate before calling

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;
}

Type guard

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 / catch

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();
  }
}

Prevention

Point DEVICE_CODE_URL at the official xAI endpoint only
Bypass proxies/captive portals that can return 2xx with HTML or empty JSON
Validate response shape (as above) when stubbing the endpoint in tests
Retry once on malformed 2xx bodies before failing the flow

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

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

Appendix: 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)