{"record":{"id":"ab3558feb5749ae8","repo":"vercel/ai","slug":"acp-environment-variable-name-is-invalid-json-s-ab3558","errorCode":null,"errorMessage":"ACP environment variable name is invalid: ${JSON.stringify(name)}.","messagePattern":"ACP environment variable name is invalid: (.+?)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/implementation.ts","lineNumber":357,"sourceCode":"    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)}.`,\n      );\n    }\n  }\n}\n\nfunction getImplementationEnvironmentKeys({\n  implementation,\n}: {\n  implementation: ACPImplementation;\n}): string[] {\n  return [\n    ...new Set([\n      ...(implementation.forwardEnv ?? []),\n      ...(implementation.credentialEnv ?? []),\n      ...Object.keys(implementation.env ?? {}),\n    ]),\n  ].sort();","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/implementation.ts#L339-L375","documentation":"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.","triggerScenarios":"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\"`).","commonSituations":"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.","solutions":["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).","If you passed `KEY=value` pairs, pass only the variable names — the harness forwards the values itself.","Trim whitespace / empty strings from the array (filter entries before passing).","Validate entries locally with the same regex before constructing the harness config to get a clearer error pointing at the exact entry."],"exampleFix":"// before\ncreateAcp({ forwardEnv: ['PATH', 'MY-PROJECT-ROOT', ''] });\n// after\ncreateAcp({ forwardEnv: ['PATH', 'MY_PROJECT_ROOT'].filter(n => /^[A-Za-z_][A-Za-z0-9_]*$/.test(n)) });","handlingStrategy":"validation","validationCode":"const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;\nfunction assertValidForwardEnv(names) {\n  for (const name of names ?? []) {\n    if (!ENV_NAME_RE.test(name)) {\n      throw new TypeError(`forwardEnv entry is not a valid env var name: ${JSON.stringify(name)}`);\n    }\n  }\n}\nassertValidForwardEnv(settings.forwardEnv);","typeGuard":"function isValidEnvName(name) {\n  return typeof name === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);\n}","tryCatchPattern":"try {\n  const harness = createAcp({ forwardEnv });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('ACP environment variable name is invalid')) {\n    const bad = JSON.parse(err.message.match(/invalid: (.*)\\./)[1]);\n    console.error(`Fix forwardEnv entry: ${bad}`);\n  } else throw err;\n}","preventionTips":["Filter forwardEnv with the regex /^[A-Za-z_][A-Za-z0-9_]*$/ before constructing settings","Pass bare variable names, never KEY=value assignments","Trim and drop empty strings from env-file-derived lists"],"tags":["validation","configuration","environment-variables","harness-acp"],"backgroundTag":"invalid-environment-variable-name","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}