vercel/ai · error · Error

ACP resolved environment value ${name} is unavailable.

Error message

ACP resolved environment value ${name} is unavailable.

What it means

requireResolvedEnvironmentValue is a lookup helper used by resolveProviderEnvironment: it fetches a named value from an already-resolved environment record and throws if it is null/undefined. Hitting this means an env var the provider configuration requires was expected to be present in the resolved environment but was not, so downstream provider setup cannot proceed.

Source

Thrown at packages/harness-acp/src/v1/acp-v1-harness.ts:841

      value.$source === 'gateway-api-key' ||
      value.$source === 'gateway-authorization'
    );
  }
  return Object.values(value).some(item =>
    containsACPProviderCredential({ value: item }),
  );
}

function requireResolvedEnvironmentValue({
  environment,
  name,
}: {
  environment: Readonly<Record<string, string>>;
  name: string;
}): string {
  const value = environment[name];
  if (value == null) {
    throw new Error(`ACP resolved environment value ${name} is unavailable.`);
  }
  return value;
}

function resolveBridgePort({
  sandboxSession,
  override,
  harnessId,
}: {
  sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
  override: number | undefined;
  harnessId: string;
}): number {
  if (override !== undefined) return override;
  if ('ports' in sandboxSession && sandboxSession.ports.length > 0) {
    return sandboxSession.ports[0];
  }
  throw unsupported({

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Set the missing environment variable in the process environment before creating the harness.
2. Check credentialEnv/credentialBrokering configuration so the value is actually injected into the resolved environment.
3. Verify the variable name spelling matches between declaration and environment.
4. Log/inspect the resolved environment record to see which keys are actually present.

Example fix

// before
// env lacks ANTHROPIC_API_KEY; resolveProviderEnvironment throws
// after
export ANTHROPIC_API_KEY=sk-...  # or add to credentialEnv so it is brokered in

function requireEnv(name: string): string {
  const value = process.env[name];
  if (value == null) throw new Error(`Missing required env var ${name}`);
  return value;
}
// call for each expected key before createACP
requireEnv('ANTHROPIC_API_KEY');

When it happens

Trigger: resolveProviderEnvironment resolving the environment map and then calling requireResolvedEnvironmentValue({ environment, name }) for a key (e.g. a provider API key or credential-brokered value) that is absent or explicitly undefined in the resolved record.

Common situations: A credentialEnv mapping references a variable that is not actually set in the process environment; brokering produced no value for the key; typos between the declared and actual env var names; running outside the environment (e.g. local vs sandbox) where the variable exists.

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

• ${description} API key is missing. Pass it using the 'apiKey
• AI Gateway authentication was selected, but neither AI_GATEW
• ACP runtime environment key ${JSON.stringify(key)} cannot be
• ACP runtime environment key ${JSON.stringify(key)} cannot be
• ACP runtime environment key ${JSON.stringify(key)} cannot be

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/cdbb99096eb889d9. Report an issue: GitHub.