alibaba/page-agent · critical · Error

[PageAgent] LLM configuration required. Please provide: base

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.

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)

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,
  },
})

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

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
}

null

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

• [PageAgent] LLMConfig.temperature is deprecated and will be
• CONFIG_ERROR
• NO_TOOL_CALL
• INVALID_TOOL_ARGS
• TOOL_EXECUTION_ERROR

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