ACP runtime environment value for ${key} contains NUL.

Error message

ACP runtime environment value for ${key} contains NUL.

What it means

Environment variable values in implementation.env must not contain NUL bytes ('\0'), since POSIX process environments are NUL-delimited and such a value would corrupt or truncate the spawned subprocess's environment. The check runs per-entry inside validateEnvironment after the name check.

Source

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

    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

Strip or reject NUL characters in the value before configuring: value.replace(/\0/g, '').
Fix the producer of the value to decode Buffers as UTF-8 (buf.toString('utf8')) instead of implicit byte-to-string conversion.
Validate/sanitize all externally sourced env values before passing them to createACPV1.

Example fix

// before
createACPV1({ env: { TOKEN: rawBufferValue.toString() } }); // may contain \0
// after
createACPV1({ env: { TOKEN: rawBufferValue.toString('utf8').replace(/\0/g, '') } });

Defensive patterns

Strategy: validation

Validate before calling

for (const [key, value] of Object.entries(env ?? {})) {
  if (value.includes('\0')) {
    throw new Error(`NUL byte in env value for ${key}`);
  }
}

Type guard

function isNulFreeEnvValue(value) {
  return typeof value === 'string' && !value.includes('\0');
}

Try / catch

try {
  const impl = createACPV1(settings);
} catch (err) {
  if (err instanceof Error && err.message.includes('contains NUL')) {
    console.error('Sanitize the env value: strip NUL bytes and fix its decoding');
  }
  throw err;
}

Prevention

Always decode Buffers with an explicit encoding (toString('utf8')) before using as env values
Sanitize externally sourced values with replace(/\0/g, '')
Never put binary data into environment variables; pass it via files or stdin instead

When it happens

Trigger: createACPV1 where any env value contains '\0' — typically from binary data decoded into a string, buffer slicing mistakes, or config parsers that leave embedded NULs in YAML/JSON strings.

Common situations: Reading a secret from a binary file, concatenating Buffer content without toString, or receiving input from an untrusted source that embeds NUL terminators.

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

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