{"record":{"id":"c533f2340ec9adaa","repo":"mastra-ai/mastra","slug":"invalid-worker-environment-variable-name-key","errorCode":null,"errorMessage":"Invalid worker environment variable name: ${key}","messagePattern":"Invalid worker environment variable name: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"deployers/sandbox/src/worker.ts","lineNumber":172,"sourceCode":"    terminationGraceMs: options.terminationGraceMs ?? 5_000,\n  };\n  const info = await getInfoSafe(options.sandbox);\n  return execution(config, options.executionId, info?.id ?? options.sandbox.id, info?.timeoutAt);\n}\n\nfunction validateOptions(options: DeployWorkerToSandboxOptions): void {\n  if (!options.sandbox.executeCommand) {\n    throw new Error(\n      `Sandbox provider \"${options.sandbox.provider}\" does not support executeCommand, which is required for worker deploys.`,\n    );\n  }\n  validateExecutionId(options.executionId);\n  if (!options.command || /[\\0\\r\\n]/.test(options.command)) {\n    throw new Error('Worker command must be a non-empty executable path.');\n  }\n  if (options.args?.some(arg => arg.includes('\\0'))) throw new Error('Worker arguments must not contain NUL bytes.');\n  for (const key of Object.keys(options.env ?? {})) {\n    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`Invalid worker environment variable name: ${key}`);\n  }\n  validateRelativePath(options.workingDirectory ?? '.', 'workingDirectory');\n  validateInput(options.input);\n  for (const [name, value] of [\n    ['inputLimitBytes', options.inputLimitBytes],\n    ['startupTimeoutMs', options.startupTimeoutMs],\n    ['executionTimeoutMs', options.executionTimeoutMs],\n    ['terminationGraceMs', options.terminationGraceMs],\n  ] as const) {\n    if (value !== undefined && (!Number.isFinite(value) || value <= 0))\n      throw new Error(`${name} must be greater than zero.`);\n  }\n  const resourceLimits = options.resourceLimits;\n  if (resourceLimits) {\n    const knownLimits = new Set(['cpuTimeSeconds', 'addressSpaceBytes', 'fileSizeBytes', 'openFiles']);\n    for (const name of Object.keys(resourceLimits)) {\n      if (!knownLimits.has(name)) throw new Error(`Unknown worker resource limit: ${name}.`);\n    }","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/sandbox/src/worker.ts#L154-L190","documentation":"Worker environment variables are passed as a plain object and must use valid POSIX identifier names: starting with a letter or underscore and containing only [A-Za-z0-9_]. Keys that fail the regex are rejected with the offending key in the message.","triggerScenarios":"Passing options.env with keys like 'MY-VAR', '2FA_TOKEN', 'my var', or empty-string keys to deployWorkerToSandbox.","commonSituations":"Copy-pasting .env lines with dashes; letting secrets-manager key names flow through unchanged; accidentally including comments ('# NOTE') or empty lines as keys when parsing env files manually.","solutions":["Rename the variable to a valid POSIX identifier (letters, digits, underscores; no leading digit).","Filter or map invalid keys out of the env object before calling deployWorkerToSandbox.","Sanitize when importing from external config: normalize keys (replace - and . with _) and drop empties."],"exampleFix":"// before\nawait deployWorkerToSandbox({ sandbox, command: 'node', env: { 'MY-KEY': 'v' } });\n// after\nawait deployWorkerToSandbox({ sandbox, command: 'node', env: { MY_KEY: 'v' } });","handlingStrategy":"validation","validationCode":"for (const key of Object.keys(env ?? {})) {\n  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`Invalid worker env var name: ${key}`);\n}","typeGuard":"const isValidEnvKey = (k: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*$/.test(k);","tryCatchPattern":null,"preventionTips":["Normalize external keys (replace '-' and '.' with '_') before passing env","Drop comments/blank lines when parsing .env files manually","Enforce the identifier regex in your deploy config schema"],"tags":["worker","validation","environment-variables"],"backgroundTag":"invalid-option-value","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}