mastra-ai/mastra · error

MASTRA_ORG_ID and MASTRA_PROJECT_ID (or --org/--project flag

Error message

MASTRA_ORG_ID and MASTRA_PROJECT_ID (or --org/--project flags, or .mastra-project.json) are required when MASTRA_API_TOKEN is set

What it means

When MASTRA_API_TOKEN is set, deploy runs headless (no interactive prompts). Headless mode requires a fully specified target: an org id and a project id must come from MASTRA_ORG_ID/MASTRA_PROJECT_ID env vars, --org/--project flags, or .mastra-project.json. If either is missing the CLI throws rather than prompting.

Source

Thrown at packages/cli/src/commands/server/deploy.ts:400

  const packageName = getPackageName(targetDir);

  // Step 1: Auth
  let token: string;
  try {
    token = await getToken();
  } catch {
    p.log.error(`Authentication failed. Run: mastra auth login`);
    process.exit(1);
  }

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

  // Step 3: Resolve org — flags and config are checked before requiring env vars
  const hasOrg = Boolean(process.env.MASTRA_ORG_ID || opts.org || projectConfig?.organizationId);
  const hasProject = Boolean(process.env.MASTRA_PROJECT_ID || opts.project || projectConfig?.projectId);
  if (isHeadless && (!hasOrg || !hasProject)) {
    throw new Error(
      'MASTRA_ORG_ID and MASTRA_PROJECT_ID (or --org/--project flags, or .mastra-project.json) are required when MASTRA_API_TOKEN is set',
    );
  }

  const { orgId, orgName } = await resolveOrg(token, projectConfig, opts.org);

  // Step 4: Resolve project
  const { projectId, projectName, projectSlug } = await resolveProject(
    token,
    orgId,
    projectConfig,
    opts.project,
    packageName,
    autoAccept,
  );

  // Step 5: Confirmation
  const isAlreadyLinked = projectConfig?.projectId === projectId && projectConfig?.organizationId === orgId;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set both MASTRA_ORG_ID and MASTRA_PROJECT_ID (e.g. as CI secrets)
2. Pass --org <id> and --project <id-or-slug> on the command line
3. Commit/restore .mastra-project.json with organizationId and projectId in the deploy directory
4. Unset MASTRA_API_TOKEN if you actually want the interactive flow

Example fix

// before (CI env)
MASTRA_API_TOKEN=*** npx mastra server deploy --yes
// after
MASTRA_API_TOKEN=*** MASTRA_ORG_ID=org_123 MASTRA_PROJECT_ID=proj_456 npx mastra server deploy --yes

// Preflight before invoking headless deploy
const required = ['MASTRA_API_TOKEN', 'MASTRA_ORG_ID', 'MASTRA_PROJECT_ID'] as const;
for (const v of required) {
  if (!process.env[v]) throw new Error(`${v} must be set for headless deploy`);
}

function hasHeadlessEnv(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 {
  await deploy();
} catch (err) {
  if (err instanceof Error && err.message.includes('MASTRA_ORG_ID and MASTRA_PROJECT_ID')) {
    console.error('Headless mode needs org+project: set MASTRA_ORG_ID/MASTRA_PROJECT_ID or pass --org/--project.');
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Exporting MASTRA_API_TOKEN (or running in CI with it set) and calling `mastra server deploy` with neither MASTRA_ORG_ID nor --org nor projectConfig.organizationId, OR with neither MASTRA_PROJECT_ID nor --project nor projectConfig.projectId — i.e. isHeadless && (!hasOrg || !hasProject).

Common situations: CI secret contains the API token but not org/project ids; developer exported MASTRA_API_TOKEN locally for testing then ran deploy expecting interactive prompts; .mastra-project.json deleted or only partially populated (org set, project missing).

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

• MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA
• Not logged in. Run `mastra auth login` interactively or set
• MASTRA_ORG_ID and MASTRA_PROJECT_ID are required when MASTRA
• Found ${existing.length} existing project(s) in this organiz
• No organization selected. Run: mastra auth orgs switch

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