vercel/ai · error

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

Error message

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

What it means

The ACP harness validates every name listed in `forwardEnv` against `/^[A-Za-z_][A-Za-z0-9_]*$/` before starting the agent. A name in that array is not a syntactically valid environment-variable identifier (e.g. contains `-`, `.`, spaces, is empty, or starts with a digit), so the harness refuses to run rather than forwarding something the OS/shell could never resolve.

Source

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

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

function getImplementationEnvironmentKeys({
  implementation,
}: {
  implementation: ACPImplementation;
}): string[] {
  return [
    ...new Set([
      ...(implementation.forwardEnv ?? []),
      ...(implementation.credentialEnv ?? []),
      ...Object.keys(implementation.env ?? {}),
    ]),
  ].sort();

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Remove or rename the offending `forwardEnv` entry so it matches /^[A-Za-z_][A-Za-z0-9_]*$/ (letters, digits, underscores; cannot start with a digit).
2. If you passed `KEY=value` pairs, pass only the variable names — the harness forwards the values itself.
3. Trim whitespace / empty strings from the array (filter entries before passing).
4. Validate entries locally with the same regex before constructing the harness config to get a clearer error pointing at the exact entry.

Example fix

// before
createAcp({ forwardEnv: ['PATH', 'MY-PROJECT-ROOT', ''] });
// after
createAcp({ forwardEnv: ['PATH', 'MY_PROJECT_ROOT'].filter(n => /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)) });

const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
function assertValidForwardEnv(names) {
  for (const name of names ?? []) {
    if (!ENV_NAME_RE.test(name)) {
      throw new TypeError(`forwardEnv entry is not a valid env var name: ${JSON.stringify(name)}`);
    }
  }
}
assertValidForwardEnv(settings.forwardEnv);

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

try {
  const harness = createAcp({ forwardEnv });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('ACP environment variable name is invalid')) {
    const bad = JSON.parse(err.message.match(/invalid: (.*)\./)[1]);
    console.error(`Fix forwardEnv entry: ${bad}`);
  } else throw err;
}

When it happens

Trigger: Passing `forwardEnv` entries in `validateACPV1Implementation`/ACP settings that fail the regex: names like `"MY-VAR"`, `"my.var"`, `"1PATH"`, `"MY VAR"`, `""`, or values accidentally passed instead of names (e.g. `"PATH=/usr/bin"`).

Common situations: Config copied from a shell where dash-cased variable names were used; typos or stray whitespace from env files; users putting `KEY=value` assignments in `forwardEnv` instead of bare names; generated configs interpolating empty strings.

Related errors

• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.
• ACP credentialEnv and credentialBrokering must be configured
• Unsupported ACP protocol version ${JSON.stringify(version)}.
• ACP credentialEnv and credentialBrokering must be configured

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