alibaba/page-agent · critical · Error

[PageAgent] LLM configuration required. Please provide…

Error message

[PageAgent] LLM configuration required. Please provide: baseURL, model. See: https://alibaba.github.io/page-agent/docs/features/models

What it means

parseLLMConfig does runtime validation on the LLMConfig object and throws a plain Error when baseURL or model is falsy. Types claim these are required, but values from user config, env vars, or partial objects can be empty strings/undefined at runtime — hence the defensive check.

Solutions

  1. Set both baseURL and model explicitly in the LLMConfig passed to PageAgent
  2. If sourcing from env, provide defaults or fail fast with a clear message when vars are missing
  3. Verify the key names: it's baseURL (not baseUrl/API_URL) and model (not modelName)
  4. See the linked docs page for supported provider configurations

Example fix

// before
new PageAgent({ llm: { baseURL: process.env.LLM_BASE_URL, model: process.env.LLM_MODEL } })

// after
if (!process.env.LLM_BASE_URL || !process.env.LLM_MODEL) {
  throw new Error('Missing LLM_BASE_URL / LLM_MODEL environment variables')
}
new PageAgent({
  llm: {
    baseURL: process.env.LLM_BASE_URL,
    model: process.env.LLM_MODEL,
  },
})
Defensive patterns

Strategy: validation

Validate before calling

function assertLLMConfig(c: LLMConfig): void {
  if (!c?.baseURL || !c?.model) {
    throw new Error(`Missing LLM config: baseURL=${c?.baseURL}, model=${c?.model}`)
  }
}
assertLLMConfig(config)

Type guard

function hasLLMConfig(c: Partial<LLMConfig> | undefined): c is LLMConfig {
  return typeof c?.baseURL === 'string' && c.baseURL.length > 0 &&
         typeof c?.model === 'string' && c.model.length > 0
}

Try / catch

null

Prevention

When it happens

Trigger: Constructing PageAgent / parseLLMConfig with a config where baseURL or model is undefined, null, or '' — e.g. env vars not set (process.env.OPENAI_BASE_URL), or a config object built conditionally that skips the LLM block.

Common situations: Missing .env entries in deployment; typo'd env var names; config assembled from optional JSON where llm section is absent; passing an OpenAIClient config shape that doesn't have baseURL (it uses a different key).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at packages/llms/src/index.ts:86

			return await fn()
		} catch (error: unknown) {
			if ((error as any)?.name === 'AbortError') throw error
			if (error instanceof InvokeError && !error.retryable) throw error
			attempt++
			if (attempt > settings.maxRetries) throw error

			console.debug('[LLM] retryable failure, will retry:', error)
			settings.onRetry(attempt, error as Error)

			await new Promise((resolve) => setTimeout(resolve, 100))
		}
	}
}

export function parseLLMConfig(config: LLMConfig): ResolvedLLMConfig {
	// Runtime validation as defensive programming (types already guarantee these)
	if (!config.baseURL || !config.model) {
		throw new Error(
			'[PageAgent] LLM configuration required. Please provide: baseURL, model. ' +
				'See: https://alibaba.github.io/page-agent/docs/features/models'
		)
	}

	if (config.temperature !== undefined) {
		console.warn(
			'[PageAgent] LLMConfig.temperature is deprecated and will be removed in a future version. ' +
				'Use transformRequestBody to set it only for models you have verified accept it.'
		)
	}

	return {
		baseURL: config.baseURL,
		model: config.model,
		apiKey: config.apiKey || '',
		temperature: config.temperature,
		maxRetries: config.maxRetries ?? 2,

View on GitHub (pinned to d02db1ee7c)