{"record":{"id":"7f5c00a2adcd6b58","repo":"mastra-ai/mastra","slug":"platform-integration-missing-required-environment","errorCode":null,"errorMessage":"Platform integration: missing required environment variable MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY).","messagePattern":"Platform integration: missing required environment variable MASTRA_PLATFORM_ACCESS_TOKEN \\(or MASTRA_PLATFORM_SECRET_KEY\\)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"mastracode/factory/src/integrations/platform/api-client.ts","lineNumber":15,"sourceCode":"export interface PlatformApiClientConfig {\n  baseUrl: string;\n  accessToken: string;\n  fetchImpl?: typeof fetch;\n}\n\nexport function platformApiClientConfigFromEnv(): PlatformApiClientConfig {\n  const sharedApiUrl = process.env.MASTRA_SHARED_API_URL?.trim() || 'https://platform.mastra.ai/v1';\n  // MASTRA_PLATFORM_ACCESS_TOKEN is the credential Mastra Platform injects\n  // into deployed projects; MASTRA_PLATFORM_SECRET_KEY is the org secret key\n  // written by project scaffolding. The platform API accepts both forms.\n  const accessToken =\n    process.env.MASTRA_PLATFORM_ACCESS_TOKEN?.trim() || process.env.MASTRA_PLATFORM_SECRET_KEY?.trim();\n  if (!accessToken) {\n    throw new Error(\n      'Platform integration: missing required environment variable MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY).',\n    );\n  }\n  return { baseUrl: normalizeSharedApiUrl(sharedApiUrl), accessToken };\n}\n\nfunction normalizeSharedApiUrl(sharedApiUrl: string): string {\n  return sharedApiUrl.replace(/\\/+$/, '').replace(/\\/v1$/, '');\n}\n\nexport class PlatformApiError extends Error {\n  readonly status: number;\n  readonly retryAfterSeconds: number | null;\n\n  constructor(message: string, status: number, retryAfterSeconds: number | null = null) {\n    super(message);\n    this.name = 'PlatformApiError';\n    this.status = status;","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/integrations/platform/api-client.ts#L1-L33","documentation":"`platformApiClientConfigFromEnv` reads platform credentials from the environment and throws when neither `MASTRA_PLATFORM_ACCESS_TOKEN` nor `MASTRA_PLATFORM_SECRET_KEY` is set (after trimming). The platform API requires one of these credentials, so without them no client can be built. This is a fail-fast configuration error at client-construction time.","triggerScenarios":"Calling `platformApiClientConfigFromEnv` (directly or via the `config` factory that builds the platform API client) in an environment where `process.env.MASTRA_PLATFORM_ACCESS_TOKEN` and `process.env.MASTRA_PLATFORM_SECRET_KEY` are both unset, empty, or whitespace-only.","commonSituations":"Running locally without a `.env` file that exports the platform credentials; deploying outside Mastra Platform so the injected `MASTRA_PLATFORM_ACCESS_TOKEN` is absent; scaffolding skipped writing `MASTRA_PLATFORM_SECRET_KEY`; CI environment missing secrets; typo'd variable name or an empty value in the deployment dashboard.","solutions":["Set `MASTRA_PLATFORM_ACCESS_TOKEN` in the environment (it is injected automatically in projects deployed to Mastra Platform).","Alternatively set `MASTRA_PLATFORM_SECRET_KEY` (the org secret key written by project scaffolding).","Locally, add the variable to your `.env` file and ensure it is loaded before the client is constructed (dotenv/import 'dotenv/config').","In CI, add the secret to the pipeline's environment/secrets configuration.","Check for typos or stray whitespace-only values in the deployment settings."],"exampleFix":"// before (shell)\npnpm dev\n// after (shell)\nexport MASTRA_PLATFORM_ACCESS_TOKEN=\"pat_...\"\npnpm dev\n# or in .env:\n# MASTRA_PLATFORM_ACCESS_TOKEN=pat_...","handlingStrategy":"validation","validationCode":"const accessToken =\n  process.env.MASTRA_PLATFORM_ACCESS_TOKEN?.trim() || process.env.MASTRA_PLATFORM_SECRET_KEY?.trim();\nif (!accessToken) {\n  throw new Error('Set MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY) before starting.');\n}","typeGuard":"function hasPlatformEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { MASTRA_PLATFORM_ACCESS_TOKEN: string } {\n  return Boolean((env.MASTRA_PLATFORM_ACCESS_TOKEN ?? env.MASTRA_PLATFORM_SECRET_KEY)?.trim());\n}","tryCatchPattern":"let config;\ntry {\n  config = platformApiClientConfigFromEnv();\n} catch (e) {\n  if (e.message.includes('missing required environment variable')) {\n    console.error('Platform credentials missing: set MASTRA_PLATFORM_ACCESS_TOKEN or MASTRA_PLATFORM_SECRET_KEY.');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Add MASTRA_PLATFORM_ACCESS_TOKEN/SECRET_KEY to .env (gitignored) for local dev.","Declare required platform secrets in your CI/deployment secret manager.","Fail fast at startup: build the client early so missing env surfaces immediately.","Never construct the platform client lazily deep in request handling where the env error is harder to trace.","Check variable spelling; the loader trims whitespace but empty strings still fail."],"tags":["environment","configuration","missing-env-var","platform"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}