mastra-ai/mastra · critical · 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

When MASTRA_API_TOKEN is present the deploy runs headless (no interactive prompts), so it requires MASTRA_ORG_ID and MASTRA_PROJECT_ID to know where to deploy. runStudioDeploy checks both after loading the project's .env and throws if either is unset.

Source

Thrown at packages/cli/src/commands/studio/deploy.ts:410

      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: () => runStudioDeploy(dir, opts),
    origin: process.env.MASTRA_ANALYTICS_ORIGIN as CLI_ORIGIN | undefined,
  });
}

async function runStudioDeploy(dir: string | undefined, opts: StudioDeployOptions) {
  const targetDir = resolve(dir || process.cwd());
  // Seed MASTRA_PROJECT_ID / MASTRA_ORG_ID from the project's .env so deploys
  // auto-link to the project that `mastra init --observability` provisioned.
  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';

  p.intro('mastra studio deploy');

  // 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);

  // Step 3: Resolve org

View on GitHub (pinned to 75dd419e61)

Solutions

Export both variables alongside the token: MASTRA_ORG_ID and MASTRA_PROJECT_ID
Run `mastra init --observability` in the project so its .env provisions MASTRA_ORG_ID/MASTRA_PROJECT_ID for auto-linking
Add the two variables to your CI secret store next to MASTRA_API_TOKEN
Or drop MASTRA_API_TOKEN and run interactively to pick org/project via prompts

Example fix

// before (CI env)
MASTRA_API_TOKEN=tok_xxx
mastra studio deploy --yes
// Error: MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA_API_TOKEN is set
// after
MASTRA_API_TOKEN=tok_xxx
MASTRA_ORG_ID=org_acme
MASTRA_PROJECT_ID=prj_001
mastra studio deploy --yes

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_ORG_ID and MASTRA_PROJECT_ID alongside MASTRA_API_TOKEN');
}

Type guard

function isHeadlessEnv(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv & { MASTRA_API_TOKEN: string; MASTRA_ORG_ID: string; MASTRA_PROJECT_ID: string } {
  return Boolean(env.MASTRA_API_TOKEN && env.MASTRA_ORG_ID && env.MASTRA_PROJECT_ID);
}

Try / catch

try {
  await $`mastra studio deploy --yes`;
} catch (e) {
  if (String(e).includes('MASTRA_ORG_ID and MASTRA_PROJECT_ID are required')) {
    console.error('Add MASTRA_ORG_ID/MASTRA_PROJECT_ID to CI secrets or run `mastra init --observability`.');
    process.exitCode = 2;
  } else throw e;
}

Prevention

Store MASTRA_ORG_ID and MASTRA_PROJECT_ID as CI secrets next to MASTRA_API_TOKEN
Run `mastra init --observability` once so the project .env seeds both ids
Add a pre-deploy env assertion step in CI
Never set MASTRA_API_TOKEN without the two ids in headless environments

When it happens

Trigger: Setting MASTRA_API_TOKEN in the environment (CI, scripts) without exporting MASTRA_ORG_ID and/or MASTRA_PROJECT_ID, and the project's .env file does not seed them (no prior `mastra init --observability`).

Common situations: CI pipelines that provision only the API token secret; running deploy from a directory whose .env lacks MASTRA_ORG_ID/MASTRA_PROJECT_ID; forgetting that the values can also come from .env, not just shell env.

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/007c5c0286eadb40. Report an issue: GitHub.