Provider : "baseUrl" is required when defining custom…

Error message

Provider ${providerName}: "baseUrl" is required when defining custom models.

What it means

In models-config/runtime mode, validateProviderConfiguration requires `baseUrl` whenever the provider defines custom `models`. Models need an endpoint to send requests to; a provider with a models list but no baseUrl cannot construct request URLs, so the error is thrown naming the provider.

Solutions

Add `baseUrl` to the provider config (typically ending in /v1 for OpenAI-compatible backends).
Check the key spelling is exactly `baseUrl` (camelCase), not baseURL or base_url.
If models were listed only to override metadata of a bundled provider, use `modelOverrides` on the named provider instead of a fresh custom provider without baseUrl.

Example fix

// before
{ "provider": "gw", "apiKey": "sk-...", "models": [{ "id": "mini" }] }
// after
{ "provider": "gw", "baseUrl": "https://gw.example.com/v1", "apiKey": "sk-...", "models": [{ "id": "mini" }] }

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.models?.length && !cfg.baseUrl) {
  throw new Error(`Provider ${cfg.provider}: add "baseUrl" when listing models`);
}

Type guard

function hasBaseUrlForModels(cfg: { baseUrl?: string; models?: unknown[] }): cfg is { baseUrl: string; models?: unknown[] } {
  return !(cfg.models?.length) || typeof cfg.baseUrl === "string" && cfg.baseUrl.length > 0;
}

Try / catch

try {
  modelsConfig.apply(parsed);
} catch (err) {
  if (err instanceof Error && err.message.includes('"baseUrl" is required when defining custom models')) {
    const provider = err.message.match(/Provider ([^:]+):/)?.[1];
    throw new Error(`Add baseUrl to provider "${provider}" in your models config`);
  }
  throw err;
}

Prevention

Always write baseUrl next to models in the same provider block.
Use the exact camelCase key `baseUrl`; baseURL/base_url silently fail validation.
For bundled/hosted providers use modelOverrides rather than redefining models without a URL.
Schema-validate config files before loading them.

When it happens

Trigger: registerProvider or ModelsConfigFile validation with `{ models: [...] }` (or modelOverrides implying models) but no `config.baseUrl` — for example defining model ids under a provider whose baseUrl line was forgotten or deleted.

Common situations: Copying a provider block and removing baseUrl because 'the hosted API has a known URL' (the library does not infer it for custom providers); refactoring shared config where baseUrl moved to a different key; typo `baseURL`/`base_url` instead of `baseUrl`.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/774c631acbb0ec6c. Report an issue: GitHub.

Appendix: source

Thrown at packages/coding-agent/src/config/models-config.ts:66

				!config.baseUrl &&
				!config.headers &&
				!config.compat &&
				!config.apiKey &&
				config.auth !== "none" &&
				!config.disableStrictTools &&
				!config.guardrailIdentifier &&
				!config.remoteCompaction &&
				!hasModelOverrides &&
				!config.discovery
			) {
				throw new Error(
					`Provider ${providerName}: must specify "baseUrl", "headers", "apiKey", "auth: none", "compat", "disableStrictTools", "guardrailIdentifier", "remoteCompaction", "modelOverrides", "discovery", or "models"`,
				);
			}
		}
	} else {
		if (!config.baseUrl) {
			throw new Error(`Provider ${providerName}: "baseUrl" is required when defining custom models.`);
		}
		const requiresAuth =
			mode === "runtime-register"
				? !config.apiKey && !config.oauthConfigured
				: !config.apiKey && (config.auth ?? "apiKey") !== "none" && (config.auth ?? "apiKey") !== "oauth";
		if (requiresAuth) {
			throw new Error(
				mode === "runtime-register"
					? `Provider ${providerName}: "apiKey" or "oauth" is required when defining models.`
					: `Provider ${providerName}: "apiKey" is required when defining custom models unless auth is "none" or "oauth".`,
			);
		}
	}

	if (mode === "models-config" && config.discovery && !config.api && config.discovery.type !== "proxy") {
		throw new Error(`Provider ${providerName}: "api" is required when discovery is enabled at provider level.`);
	}

View on GitHub (pinned to 9690622007)