Worker executionId must contain only letters, numbers, dots,

Error message

Worker executionId must contain only letters, numbers, dots, underscores, and hyphens.

What it means

The sandbox worker validates its executionId against EXECUTION_ID_PATTERN before running any phase (upload/install/launch). An empty executionId or one containing characters outside [letters, numbers, dots, underscores, hyphens] is rejected because the id is used to build filesystem paths and shell arguments, where unsafe characters could break commands or enable path traversal.

Source

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

function executionPaths(remoteDir: string, executionId: string) {
  const dir = `${remoteDir}/${RUNTIME_DIR}/${executionId}`;
  return {
    executionId,
    dir,
    script: `${dir}/launch.sh`,
    pid: `${dir}/pid`,
    pidToken: `${dir}/pid-start`,
    status: `${dir}/status`,
    stdin: `${dir}/stdin`,
    stdout: `${dir}/stdout`,
    stderr: `${dir}/stderr`,
  };
}

function validateExecutionId(executionId: string): void {
  if (!executionId || !EXECUTION_ID_PATTERN.test(executionId)) {
    throw new Error('Worker executionId must contain only letters, numbers, dots, underscores, and hyphens.');
  }
}

function workerPhaseError(phase: 'upload' | 'install' | 'launch', error: unknown): Error {
  return new Error(`Worker ${phase} failed: ${errorMessage(error)}`, { cause: error });
}

function errorMessage(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

function sanitizeStatusValue(value: string): string {
  return value.replace(/[|\r\n]/g, ' ').slice(0, 500);
}

View on GitHub (pinned to 75dd419e61)

Solutions

Sanitize the executionId before passing it to the worker (strip or replace disallowed characters).
Use a generated id such as a UUID with hyphens or nanoid from an alphabet of letters/digits.
Add a validation check at the call site so invalid ids fail early with a clear message.

Example fix

// before
runWorker({ executionId: `${runId}` }); // runId = 'runs/2026/08 29'
// after
const safeId = runId.replace(/[^a-zA-Z0-9._-]/g, '-');
runWorker({ executionId: safeId });

Defensive patterns

Strategy: validation

Validate before calling

const EXECUTION_ID_PATTERN = /^[a-zA-Z0-9._-]+$/;
if (!executionId || !EXECUTION_ID_PATTERN.test(executionId)) {
  throw new Error(`Invalid executionId: ${JSON.stringify(executionId)}`);
}
runWorker({ executionId });

Type guard

function isValidExecutionId(id: unknown): id is string {
  return typeof id === 'string' && /^[a-zA-Z0-9._-]+$/.test(id);
}

Try / catch

try {
  await runWorker({ executionId });
} catch (err) {
  if ((err as Error).message.includes('executionId must contain')) {
    console.error('Bad executionId, sanitize and retry:', executionId);
  }
  throw err;
}

Prevention

Generate execution ids from a UUID or other [a-zA-Z0-9._-]-safe alphabet.
Sanitize user-derived ids by replacing disallowed characters before use.
Never pass raw URLs, paths, or timestamps with slashes/spaces as ids.
Validate ids at the entry point of your pipeline, before spawning workers.

When it happens

Trigger: Calling the sandbox worker (or deployer that drives it) with an executionId that is empty, contains slashes, spaces, whitespace, '@', ':', or other special characters not matching the allowed pattern.

Common situations: Generating execution ids from user input, URLs, timestamps with separators like '/' or spaces, or passing undefined/empty values when run metadata is missing.

Related errors

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