mastra-ai/mastra · error

Worker arguments must not contain NUL bytes.

Error message

Worker arguments must not contain NUL bytes.

What it means

Worker arguments are forwarded to the provider exec API as an argv array; NUL bytes cannot appear in a real argv entry on POSIX systems, so any arg containing \0 is rejected during validation.

Source

Thrown at deployers/sandbox/src/worker.ts:170

    sandbox: options.sandbox,
    resolveRemoteDir: async () => (remoteDir ??= await resolveRemoteDir(options.sandbox, options.remoteDir)),
    terminationGraceMs: options.terminationGraceMs ?? 5_000,
  };
  const info = await getInfoSafe(options.sandbox);
  return execution(config, options.executionId, info?.id ?? options.sandbox.id, info?.timeoutAt);
}

function validateOptions(options: DeployWorkerToSandboxOptions): void {
  if (!options.sandbox.executeCommand) {
    throw new Error(
      `Sandbox provider "${options.sandbox.provider}" does not support executeCommand, which is required for worker deploys.`,
    );
  }
  validateExecutionId(options.executionId);
  if (!options.command || /[\0\r\n]/.test(options.command)) {
    throw new Error('Worker command must be a non-empty executable path.');
  }
  if (options.args?.some(arg => arg.includes('\0'))) throw new Error('Worker arguments must not contain NUL bytes.');
  for (const key of Object.keys(options.env ?? {})) {
    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`Invalid worker environment variable name: ${key}`);
  }
  validateRelativePath(options.workingDirectory ?? '.', 'workingDirectory');
  validateInput(options.input);
  for (const [name, value] of [
    ['inputLimitBytes', options.inputLimitBytes],
    ['startupTimeoutMs', options.startupTimeoutMs],
    ['executionTimeoutMs', options.executionTimeoutMs],
    ['terminationGraceMs', options.terminationGraceMs],
  ] as const) {
    if (value !== undefined && (!Number.isFinite(value) || value <= 0))
      throw new Error(`${name} must be greater than zero.`);
  }
  const resourceLimits = options.resourceLimits;
  if (resourceLimits) {
    const knownLimits = new Set(['cpuTimeSeconds', 'addressSpaceBytes', 'fileSizeBytes', 'openFiles']);
    for (const name of Object.keys(resourceLimits)) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Strip or split on NUL bytes before passing args (e.g. arg.replace(/\0/g, '') or buffer.toString('utf8')).
2. Ensure args originate from string sources, not raw Buffers with terminator bytes.
3. Log and inspect the offending arg if the source is untrusted input.

Example fix

// before
const args = [buffer.toString('binary')]; // may contain \0
await deployWorkerToSandbox({ sandbox, command: 'node', args });
// after
const args = [buffer.toString('utf8').replace(/\0/g, '')];
await deployWorkerToSandbox({ sandbox, command: 'node', args });

if (args?.some(a => a.includes('\0'))) throw new Error('Worker arguments must not contain NUL bytes');

const hasNoNul = (args: unknown): args is string[] =>
  Array.isArray(args) && args.every(a => typeof a === 'string' && !a.includes('\0'));

When it happens

Trigger: Passing options.args where at least one string includes the \0 character.

Common situations: Arguments read from binary buffers without UTF-8 sanitization; values sliced from C-style buffers including the terminating NUL; corrupt or malicious config input.

Understand the failure class

Background: Invalid option value errors: "must be one of", "is not a valid", and "only allows" failures explained — this error's family across 23 libraries.

Related errors

• terminationGraceMs must be greater than zero.
• Worker command must be a non-empty executable path.
• Invalid worker environment variable name: ${key}
• ${name} must be greater than zero.
• Unknown worker resource limit: ${name}.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/6c1c1e6810f6a708. Report an issue: GitHub.