mastra-ai/mastra · error

Worker command must be a non-empty executable path.

Error message

Worker command must be a non-empty executable path.

What it means

The worker `command` must be a non-empty executable path and is passed to the provider exec API as argv[0], so it must not contain NUL, CR, or LF characters. validateOptions rejects empty strings and control characters up front.

Source

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

  let remoteDir: string | undefined;
  const config: WorkerExecutionConfig = {
    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) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a bare executable path in `command` (e.g. 'node', '/usr/local/bin/python') and put arguments in `args`.
2. Trim/validate the value at the config boundary before calling deployWorkerToSandbox.
3. For scripts, upload the script file and execute it via its path rather than inlining shell text.

Example fix

// before
await deployWorkerToSandbox({ sandbox, command: 'node server.js\n' });
// after
await deployWorkerToSandbox({ sandbox, command: 'node', args: ['server.js'] });

if (!cmd || /[\0\r\n]/.test(cmd)) throw new Error('Worker command must be a non-empty executable path without control characters');

const isValidCommand = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0 && !/[\0\r\n]/.test(v);

When it happens

Trigger: Passing command: '' , command: undefined, or a command containing \0, \r, or \n to deployWorkerToSandbox.

Common situations: Interpolating multi-line script text into `command` instead of using `args`; reading the command from an empty env var or config field; template strings that accidentally embed newlines.

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.
• ${name} must be greater than zero.
• Unknown worker resource limit: ${name}.
• @mastra/livekit: set exactly one reply generator — `generate
• @mastra/livekit: set `agent` or `workflow`, not both — they

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