{"record":{"id":"2de19d05107c0527","repo":"paperclipai/paperclip","slug":"api-key-env-must-name-a-valid-environment-variab","errorCode":null,"errorMessage":"--api-key-env must name a valid environment variable.","messagePattern":"--api-key-env must name a valid environment variable\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/test-drive.ts","lineNumber":257,"sourceCode":"  if (!companyName) throw new Error(\"--company-name cannot be empty.\");\n  if (!agentName) throw new Error(\"--agent-name cannot be empty.\");\n\n  const model = options.model;\n  if (model !== undefined && (!model || model.trim() !== model)) {\n    throw new Error(\"--model cannot be empty or have surrounding whitespace.\");\n  }\n  if (\n    harness === \"opencode\" &&\n    (!model || !/^openrouter\\/[^/\\s]+(?:\\/[^/\\s]+)*$/.test(model))\n  ) {\n    throw new Error(\n      \"OpenCode test drives require --model openrouter/<model>, with no empty path segments.\",\n    );\n  }\n\n  const sourceEnvName = options.apiKeyEnv?.trim() || definition.credentialTarget;\n  if (options.apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(sourceEnvName)) {\n    throw new Error(\"--api-key-env must name a valid environment variable.\");\n  }\n  const credential = options.apiKey ?? env[sourceEnvName];\n  if (!credential || credential.trim().length === 0) {\n    throw new Error(\n      `No credential found. Set ${sourceEnvName}, pass --api-key-env <variable>, or pass --api-key <value>.`,\n    );\n  }\n\n  return {\n    ...definition,\n    companyName,\n    agentName,\n    ...(model ? { model } : {}),\n    credential,\n    credentialSource: options.apiKey !== undefined ? \"--api-key\" : sourceEnvName,\n  };\n}\n","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/cli/src/commands/test-drive.ts#L239-L275","documentation":"resolveTestDriveBootstrap validates the --api-key-env option. When explicitly provided, its trimmed value must be a valid environment variable name (a letter or underscore followed by letters, digits, or underscores). This error means the flag was given but its value is not a usable env var identifier.","triggerScenarios":"Passing --api-key-env with a value containing digits at the start (e.g. '1PASSWORD_API_KEY'), hyphens ('MY-API-KEY'), spaces, or an empty/whitespace-only string.","commonSituations":"Typing the env var name with hyphens instead of underscores; quoting an empty value; shell variable expansion producing an empty string (`--api-key-env \"$MY_VAR\"` when MY_VAR is unset).","solutions":["Rename the flag value to a valid identifier, e.g. --api-key-env OPENROUTER_API_KEY","If the shell variable is empty, set it before invoking the command","Omit --api-key-env entirely to fall back to the app definition's default credentialTarget"],"exampleFix":"// before\npaperclip test-drive <app> --api-key-env MY-API-KEY\n// after\npaperclip test-drive <app> --api-key-env MY_API_KEY","handlingStrategy":"validation","validationCode":"if (apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv.trim())) {\n  throw new Error('--api-key-env must be a valid env var name');\n}","typeGuard":"function isValidEnvVarName(v: unknown): v is string {\n  return typeof v === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(v);\n}","tryCatchPattern":null,"preventionTips":["Use underscores, never hyphens, in env var names","Avoid `${VAR}` expansions that may expand to empty strings","Validate names with a quick echo test before wiring into scripts"],"tags":["cli","validation","env-var"],"backgroundTag":"invalid-env-var-value","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}