Required API key ${envVarName} for provider '${providerName}

Error message

Required API key ${envVarName} for provider '${providerName}' is not set in environment, session, or .env file.

What it means

_resolveApiKey validates that providers requiring an API key actually have one. It searches the explicit apiKey argument, the session, and the .env file/environment for the provider's required env var (from getRequiredApiKeyName()). If nothing yields a key, it throws with the exact env var name so the developer knows what to set.

Source

Thrown at scripts/modules/ai-services-unified.js:406

	}

	// All providers must implement getRequiredApiKeyName()
	const envVarName = provider.getRequiredApiKeyName();

	// If envVarName is null (like for MCP), return null directly
	if (envVarName === null) {
		return null;
	}

	const apiKey = resolveEnvVariable(envVarName, session, projectRoot);

	// Special handling for providers that can use alternative auth or no API key
	if (!provider.isRequiredApiKey()) {
		return apiKey || null;
	}

	if (!apiKey) {
		throw new Error(
			`Required API key ${envVarName} for provider '${providerName}' is not set in environment, session, or .env file.`
		);
	}
	return apiKey;
}

/**
 * Internal helper to attempt a provider-specific AI API call with retries.
 *
 * @param {function} providerApiFn - The specific provider function to call (e.g., generateAnthropicText).
 * @param {object} callParams - Parameters object for the provider function.
 * @param {string} providerName - Name of the provider (for logging).
 * @param {string} modelId - Specific model ID (for logging).
 * @param {string} attemptRole - The role being attempted (for logging).
 * @returns {Promise<object>} The result from the successful API call.
 * @throws {Error} If the call fails after all retries.
 */
async function _attemptProviderCallWithRetries(

View on GitHub (pinned to c0c98d367c)

Solutions

Set the named env var (printed in the error, e.g. ANTHROPIC_API_KEY) in your shell or in the project root .env file.
Pass the key explicitly via the service's apiKey parameter if you manage keys yourself.
In CI, add the secret to the pipeline environment.
Switch to a provider that doesn't require an API key (e.g. Ollama) if you have no key.
Verify the variable name matches exactly what the provider's getRequiredApiKeyName() returns — no aliases.

Example fix

// before
# .env
ANTHROPIC_KEY=sk-... // wrong name, still throws
// after
# .env (project root)
ANTHROPIC_API_KEY=sk-ant-...

Defensive patterns

Strategy: validation

Validate before calling

// fail fast before calling the service
const key = process.env.ANTHROPIC_API_KEY; // use the provider's required var name
if (!key) {
  throw new Error('Set ANTHROPIC_API_KEY in your environment or project .env before running AI services.');
}

Type guard

function hasApiKey(envVarName) {
  return typeof process.env[envVarName] === 'string' && process.env[envVarName].length > 0;
}

Try / catch

try {
  await generateTextService({ providerName: 'anthropic', prompt });
} catch (e) {
  if (/Required API key .* is not set/.test(e.message)) {
    console.error('Missing API key: copy .env.example to .env and fill in the listed key.');
    process.exitCode = 1;
  } else throw e;
}

Prevention

Copy .env.example to .env during project setup and commit .env.example (never .env).
In CI, declare all required provider secrets explicitly.
Check the exact env var name in the error message — aliases are not accepted.
For local dev without keys, switch to a keyless provider like Ollama.

When it happens

Trigger: Calling generateTextService/generateObjectService/stream* for a provider whose required key (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY) is absent from the environment, the mcpSession/global session, and the project's .env file, while the provider's isRequiredApiKey() is true.

Common situations: Fresh clone without .env set up, CI pipelines missing secrets, keys defined in a different .env location than the project root, key set under the wrong variable name, or using a key-requiring provider (e.g. Anthropic) where a keyless one (Ollama) was intended.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/8c83dcbb414b502a. Report an issue: GitHub.