vercel/ai · error

ACP environment variable name is invalid: ${JSON.stringify(k

Error message

ACP environment variable name is invalid: ${JSON.stringify(key)}.

What it means

Every key in implementation.env must be a valid environment variable name: starting with a letter or underscore, followed only by letters, digits, and underscores (ENVIRONMENT_VARIABLE_NAME_REGEXP). createACPV1 validates each entry because the subprocess spawn would otherwise fail or silently drop the variable. The message reports the offending key via JSON.stringify.

Source

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

  }
  if (
    source.packageVersion != null &&
    !EXACT_SEMVER_REGEXP.test(source.packageVersion)
  ) {
    throw new Error(
      `ACP npm package version must be an exact semantic version; received ${JSON.stringify(source.packageVersion)}.`,
    );
  }
}

function validateEnvironment({
  env,
}: {
  env: Readonly<Record<string, string>> | undefined;
}): void {
  for (const [key, value] of Object.entries(env ?? {})) {
    if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(key)) {
      throw new Error(
        `ACP environment variable name is invalid: ${JSON.stringify(key)}.`,
      );
    }
    if (value.includes('\0')) {
      throw new Error(`ACP runtime environment value for ${key} contains NUL.`);
    }
  }
}

function validateForwardEnvironment({
  forwardEnv,
}: {
  forwardEnv: ReadonlyArray<string> | undefined;
}): void {
  for (const name of forwardEnv ?? []) {
    if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(name)) {
      throw new Error(
        `ACP environment variable name is invalid: ${JSON.stringify(name)}.`,

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Rename the key to a valid identifier, e.g. 'MY-VAR' -> 'MY_VAR'.
2. Check the env-building code for stray/empty keys and filter invalid names before calling createACPV1.
3. If the target process truly needs a non-standard name, set it via the command wrapper instead of env.

Example fix

// before
createACPV1({ env: { 'LOG-LEVEL': 'debug' } });
// after
createACPV1({ env: { LOG_LEVEL: 'debug' } });

const ENVIRONMENT_VARIABLE_NAME_REGEXP = /^[A-Za-z_][A-Za-z0-9_]*$/;
for (const key of Object.keys(env ?? {})) {
  if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(key)) {
    throw new Error(`Invalid env var name: ${JSON.stringify(key)}`);
  }
}

function isValidEnvVarName(key) {
  return typeof key === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
}

try {
  const impl = createACPV1(settings);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('ACP environment variable name is invalid')) {
    console.error('Rename the env key to C-identifier form (letters, digits, underscore)');
  }
  throw err;
}

When it happens

Trigger: createACPV1 with env keys like 'MY-VAR', 'MY VAR', '1ST_VAR', 'my.var', or an empty-string key (e.g. from parsing a dotenv line without a name).

Common situations: Using dash-cased names by habit, pasting shell-quoted env lines into a JSON map, or programmatically building env from `env`/dotenv output that contains odd entries.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• 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
• ACP runtime environment value for ${key} contains NUL.
• Invalid argument for parameter output: Invalid output type.

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