Platform integration: missing required environment variable

Error message

Platform integration: missing required environment variable MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY).

What it means

`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.

Source

Thrown at mastracode/factory/src/integrations/platform/api-client.ts:15

export interface PlatformApiClientConfig {
  baseUrl: string;
  accessToken: string;
  fetchImpl?: typeof fetch;
}

export function platformApiClientConfigFromEnv(): PlatformApiClientConfig {
  const sharedApiUrl = process.env.MASTRA_SHARED_API_URL?.trim() || 'https://platform.mastra.ai/v1';
  // MASTRA_PLATFORM_ACCESS_TOKEN is the credential Mastra Platform injects
  // into deployed projects; MASTRA_PLATFORM_SECRET_KEY is the org secret key
  // written by project scaffolding. The platform API accepts both forms.
  const accessToken =
    process.env.MASTRA_PLATFORM_ACCESS_TOKEN?.trim() || process.env.MASTRA_PLATFORM_SECRET_KEY?.trim();
  if (!accessToken) {
    throw new Error(
      'Platform integration: missing required environment variable MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY).',
    );
  }
  return { baseUrl: normalizeSharedApiUrl(sharedApiUrl), accessToken };
}

function normalizeSharedApiUrl(sharedApiUrl: string): string {
  return sharedApiUrl.replace(/\/+$/, '').replace(/\/v1$/, '');
}

export class PlatformApiError extends Error {
  readonly status: number;
  readonly retryAfterSeconds: number | null;

  constructor(message: string, status: number, retryAfterSeconds: number | null = null) {
    super(message);
    this.name = 'PlatformApiError';
    this.status = status;

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before (shell)
pnpm dev
// after (shell)
export MASTRA_PLATFORM_ACCESS_TOKEN="pat_..."
pnpm dev
# or in .env:
# MASTRA_PLATFORM_ACCESS_TOKEN=pat_...

Defensive patterns

Strategy: validation

Validate before calling

const accessToken =
  process.env.MASTRA_PLATFORM_ACCESS_TOKEN?.trim() || process.env.MASTRA_PLATFORM_SECRET_KEY?.trim();
if (!accessToken) {
  throw new Error('Set MASTRA_PLATFORM_ACCESS_TOKEN (or MASTRA_PLATFORM_SECRET_KEY) before starting.');
}

Type guard

function hasPlatformEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { MASTRA_PLATFORM_ACCESS_TOKEN: string } {
  return Boolean((env.MASTRA_PLATFORM_ACCESS_TOKEN ?? env.MASTRA_PLATFORM_SECRET_KEY)?.trim());
}

Try / catch

let config;
try {
  config = platformApiClientConfigFromEnv();
} catch (e) {
  if (e.message.includes('missing required environment variable')) {
    console.error('Platform credentials missing: set MASTRA_PLATFORM_ACCESS_TOKEN or MASTRA_PLATFORM_SECRET_KEY.');
    process.exit(1);
  }
  throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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