{"record":{"id":"612b9ef90a4ae1f6","repo":"vercel/ai","slug":"acp-environment-variable-name-is-invalid-json-s","errorCode":null,"errorMessage":"ACP environment variable name is invalid: ${JSON.stringify(key)}.","messagePattern":"ACP environment variable name is invalid: (.+?)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/implementation.ts","lineNumber":340,"sourceCode":"  }\n  if (\n    source.packageVersion != null &&\n    !EXACT_SEMVER_REGEXP.test(source.packageVersion)\n  ) {\n    throw new Error(\n      `ACP npm package version must be an exact semantic version; received ${JSON.stringify(source.packageVersion)}.`,\n    );\n  }\n}\n\nfunction validateEnvironment({\n  env,\n}: {\n  env: Readonly<Record<string, string>> | undefined;\n}): void {\n  for (const [key, value] of Object.entries(env ?? {})) {\n    if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(key)) {\n      throw new Error(\n        `ACP environment variable name is invalid: ${JSON.stringify(key)}.`,\n      );\n    }\n    if (value.includes('\\0')) {\n      throw new Error(`ACP runtime environment value for ${key} contains NUL.`);\n    }\n  }\n}\n\nfunction validateForwardEnvironment({\n  forwardEnv,\n}: {\n  forwardEnv: ReadonlyArray<string> | undefined;\n}): void {\n  for (const name of forwardEnv ?? []) {\n    if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(name)) {\n      throw new Error(\n        `ACP environment variable name is invalid: ${JSON.stringify(name)}.`,","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/implementation.ts#L322-L358","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Rename the key to a valid identifier, e.g. 'MY-VAR' -> 'MY_VAR'.","Check the env-building code for stray/empty keys and filter invalid names before calling createACPV1.","If the target process truly needs a non-standard name, set it via the command wrapper instead of env."],"exampleFix":"// before\ncreateACPV1({ env: { 'LOG-LEVEL': 'debug' } });\n// after\ncreateACPV1({ env: { LOG_LEVEL: 'debug' } });","handlingStrategy":"validation","validationCode":"const ENVIRONMENT_VARIABLE_NAME_REGEXP = /^[A-Za-z_][A-Za-z0-9_]*$/;\nfor (const key of Object.keys(env ?? {})) {\n  if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(key)) {\n    throw new Error(`Invalid env var name: ${JSON.stringify(key)}`);\n  }\n}","typeGuard":"function isValidEnvVarName(key) {\n  return typeof key === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);\n}","tryCatchPattern":"try {\n  const impl = createACPV1(settings);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('ACP environment variable name is invalid')) {\n    console.error('Rename the env key to C-identifier form (letters, digits, underscore)');\n  }\n  throw err;\n}","preventionTips":["Use UPPER_SNAKE_CASE for all env keys","Filter or normalize keys when building env from dotenv/shell output","Reject empty-string keys at config-load time"],"tags":["configuration","environment","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}