mastra-ai/mastra · error · Error

MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA

Error message

MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA_API_TOKEN is set

What it means

Thrown by runUnifiedDeploy during headless-mode validation. When MASTRA_API_TOKEN is set, the CLI assumes a non-interactive CI/headless deploy, which requires MASTRA_ORG_ID and MASTRA_PROJECT_ID to identify the target. Without them the CLI cannot determine where to deploy, so it fails fast before any interactive prompting.

Source

Thrown at packages/cli/src/commands/deploy/index.ts:577

      hasEnvFile: Boolean(opts.envFile),
      hasConfig: Boolean(opts.config),
      debug: Boolean(opts.debug),
      headless: Boolean(process.env.MASTRA_API_TOKEN),
      targetApi: bucketApiHost(MASTRA_PLATFORM_API_URL),
    },
    execution: () => runUnifiedDeploy(dir, opts),
    origin: process.env.MASTRA_ANALYTICS_ORIGIN as CLI_ORIGIN | undefined,
  });
}

async function runUnifiedDeploy(dir: string | undefined, opts: DeployOptions) {
  const targetDir = resolve(dir || process.cwd());
  await assertDeployDir(dir, targetDir);
  loadDeployEnvFromDotenv(targetDir);

  const isHeadless = Boolean(process.env.MASTRA_API_TOKEN);
  if (isHeadless && (!process.env.MASTRA_ORG_ID || !process.env.MASTRA_PROJECT_ID)) {
    throw new Error('MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA_API_TOKEN is set');
  }

  const autoAccept = opts.yes ?? isHeadless;
  const skipPreflight = opts.skipPreflight || process.env.MASTRA_SKIP_PREFLIGHT === '1';
  const envName = opts.env || 'production';

  p.intro(`${pc.bold('mastra deploy')} → ${pc.cyan(envName)}`);

  // Gather context
  const packageName = getPackageName(targetDir);
  const gitBranch = getGitBranch(targetDir);
  const mastraVersion = getMastraVersion(targetDir);

  // Step 1: Auth
  const token = await getToken();

  // Step 2: Load existing project config
  const projectConfig = await loadProjectConfig(targetDir, opts.config);

View on GitHub (pinned to 75dd419e61)

Solutions

Set MASTRA_ORG_ID and MASTRA_PROJECT_ID in the environment (or in the target directory's .env) alongside MASTRA_API_TOKEN.
Copy the org ID and project ID from the Mastra dashboard and export them in your CI secrets.
If you intended an interactive deploy, unset MASTRA_API_TOKEN so the CLI can prompt for the missing values.
Check for typos — the CLI expects exactly MASTRA_ORG_ID and MASTRA_PROJECT_ID (loaded from dotenv too).

Example fix

// CI before (fails)
export MASTRA_API_TOKEN=sk-...
mastra deploy
// after
export MASTRA_API_TOKEN=sk-...
export MASTRA_ORG_ID=org_abc123
export MASTRA_PROJECT_ID=prj_xyz789
mastra deploy

Defensive patterns

Strategy: validation

Validate before calling

if (process.env.MASTRA_API_TOKEN && !(process.env.MASTRA_ORG_ID && process.env.MASTRA_PROJECT_ID)) {
  throw new Error('Headless deploy requires MASTRA_API_TOKEN + MASTRA_ORG_ID + MASTRA_PROJECT_ID');
}

Prevention

Define MASTRA_ORG_ID and MASTRA_PROJECT_ID as CI secrets alongside MASTRA_API_TOKEN.
Keep all three variables together in your project's .env file.
Use the exact variable names — no ORGANIZATION or PROJECT aliases.
Unset MASTRA_API_TOKEN for local interactive deploys.

When it happens

Trigger: process.env.MASTRA_API_TOKEN is truthy AND (MASTRA_ORG_ID is unset/empty OR MASTRA_PROJECT_ID is unset/empty) when running `mastra deploy`. This happens after loadDeployEnvFromDotenv has loaded the target dir's .env, so missing values in the environment or dotenv file both trigger it.

Common situations: CI pipeline exports the API token but forgets org/project IDs; .env file has MASTRA_API_TOKEN but not the org/project variables; typos in variable names (e.g. MASTRA_ORGANIZATION_ID); running locally with a token set in shell profile but no project context.

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/46dba35a8f32b474. Report an issue: GitHub.