alibaba/page-agent · critical · InvokeError

AUTH_ERROR

AUTH_ERROR

Error message

Authentication failed: ${errorMessage}

What it means

The endpoint returned HTTP 401 or 403, meaning the API key is missing, invalid, expired, or lacks permission for the requested resource/model. The message embeds the provider's error message from the response body (or statusText as fallback), and the parsed error body is attached as details.

Solutions

1. Verify the API key is set, non-empty, and copied exactly (no quotes/newlines)
2. Confirm the key matches the provider implied by baseURL — OpenAI keys don't work on Azure/Gemini/other compatible endpoints
3. For Azure-style endpoints, ensure the auth header and deployment name required by that provider are configured (via transformRequestHeaders/requestBody)
4. Test the key directly: curl -H "Authorization: Bearer $KEY" <baseURL>/models
5. If 403 on a specific model, switch to a model your account is entitled to

Example fix

// before
const client = new OpenAIClient({ baseURL: 'https://api.openai.com/v1', apiKey: undefined })

// after
const client = new OpenAIClient({
  baseURL: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!, // ensure it is loaded and trimmed
})

if (!cfg.apiKey || cfg.apiKey.trim().length < 20) {
  throw new Error('API key missing or suspiciously short')
}

const isAuthError = (e: unknown): e is InvokeError =>
  e instanceof InvokeError && e.code === 'AUTH_ERROR'

try {
  await client.invoke(req)
} catch (e) {
  if (isAuthError(e)) {
    // keys rarely heal — surface to user, do not retry
    throw new Error(`Check your API key: ${e.message}`)
  }
  throw e
}

When it happens

Trigger: invoke() call where the server responds 401 (bad/missing API key) or 403 (key valid but forbidden — model not entitled, org restricted, or region blocked). Common with OpenAI, Azure (wrong deployment/key header), Gemini OpenAI-compat endpoints with an invalid key.

Common situations: API key env var not set or pasted with whitespace/quotes; using an OpenAI key against an Azure or Gemini baseURL; free-tier key requesting a paid model; expired or revoked token; wrong apiKeyHeader configuration for a compatible provider.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• CONFIG_ERROR
• INVALID_RESPONSE
• INVALID_SCHEMA
• NETWORK_ERROR
• RATE_LIMIT

AI-assisted analysis of alibaba/page-agent@d02db1ee7c (2026-08-28). Data as JSON: /api/errors/0d6e63ce2f7c2587. Report an issue: GitHub.

Appendix: source

Thrown at packages/llms/src/OpenAIClient.ts:102

			})
		} catch (error: unknown) {
			if ((error as any)?.name === 'AbortError') throw error
			console.error(error)
			throw new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'Network request failed', error)
		}

		// 3. Handle HTTP errors
		if (!response.ok) {
			let errorData: any
			try {
				errorData = await response.json()
			} catch (error) {
				if ((error as any)?.name === 'AbortError') throw error
			}
			const errorMessage = errorData?.error?.message || response.statusText

			if (response.status === 401 || response.status === 403) {
				throw new InvokeError(
					InvokeErrorTypes.AUTH_ERROR,
					`Authentication failed: ${errorMessage}`,
					errorData
				)
			}
			if (response.status === 429) {
				throw new InvokeError(
					InvokeErrorTypes.RATE_LIMIT,
					`Rate limit exceeded: ${errorMessage}`,
					errorData
				)
			}
			if (response.status >= 500) {
				throw new InvokeError(
					InvokeErrorTypes.SERVER_ERROR,
					`Server error: ${errorMessage}`,
					errorData
				)

View on GitHub (pinned to d02db1ee7c)