Provider ${providerName}: "apiKey" or "oauth" is required wh

Error message

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".

What it means

validateProviderConfiguration enforces credentials for providers that define models. Two variants: in runtime-register mode, either `apiKey` or a configured OAuth login (`oauthConfigured`) must exist; in models-config mode, `apiKey` must be present unless `auth` is "none" or "oauth". The error is thrown when models are defined but no usable credential path exists.

Source

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

				!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.`);
	}

	for (const modelDef of models) {
		if (!hasProviderApi && !modelDef.api) {
			throw new Error(
				mode === "runtime-register"
					? `Provider ${providerName}, model ${modelDef.id}: no "api" specified.`
					: `Provider ${providerName}, model ${modelDef.id}: no "api" specified. Set at provider or model level.`,
			);

View on GitHub (pinned to 9690622007)

Solutions

For keyless local servers, add `"auth": "none"` to the provider config (models-config mode).
Otherwise set `apiKey` (or fix its key name / env expansion so it is non-empty).
For OAuth providers, complete the /login flow so oauthConfigured is true before registering models.
In SDK/runtime code, pass apiKey in the ProviderConfigInput or set oauthConfigured.

Example fix

// before: keyless local server
{ "provider": "local", "baseUrl": "http://localhost:11434/v1", "models": [{ "id": "qwen3" }] }
// after
{ "provider": "local", "baseUrl": "http://localhost:11434/v1", "auth": "none", "models": [{ "id": "qwen3" }] }

Defensive patterns

Strategy: validation

Validate before calling

function providerHasCredentialPath(cfg: { apiKey?: string; auth?: string; oauthConfigured?: boolean; mode: "runtime-register" | "models-config" }): boolean {
  if (cfg.mode === "runtime-register") return Boolean(cfg.apiKey || cfg.oauthConfigured);
  const auth = cfg.auth ?? "apiKey";
  return Boolean(cfg.apiKey) || auth === "none" || auth === "oauth";
}

Type guard

null

Try / catch

try {
  modelsConfig.apply(parsed);
} catch (err) {
  if (err instanceof Error && err.message.includes('"apiKey" or "oauth" is required')) {
    const provider = err.message.match(/Provider ([^:]+):/)?.[1];
    throw new Error(`Set apiKey or auth:"none" for provider "${provider}"`);
  }
  throw err;
}

Prevention

Add auth:"none" to keyless local providers (Ollama, llama.cpp, vLLM).
Verify env-var expansion leaves apiKey non-empty; empty strings still count as missing.
Complete OAuth /login before relying on oauth in runtime-register mode.
Check credential path with providerHasCredentialPath before loading config.

When it happens

Trigger: registerProvider(name, { baseUrl, models }) at runtime without apiKey and without prior OAuth login; or a models-config provider with models but no apiKey and auth unset/defaulting to "apiKey" (also fires when auth is a value other than none/oauth and apiKey is missing).

Common situations: Pointing at a local server (Ollama/llama.cpp/vLLM) that needs no key but forgetting `auth: "none"`; OAuth previously done via /login was cleared so oauthConfigured is false; apiKey defined under a wrong key name (token, api_key); env-var expansion in the config failed leaving an empty key.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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