mastra-ai/mastra · error · Error

No project specified. Pass --project <name|slug|id>, set MAS

Error message

No project specified. Pass --project <name|slug|id>, set MASTRA_PROJECT_ID, or run from a directory with a linked .mastra-project.json.

What it means

Thrown by `resolveProject` when no project identifier is available at all: no --project flag, no MASTRA_PROJECT_ID env var, and the current directory has no linked .mastra-project.json (or its projectId doesn't match a project). The CLI refuses to guess which Mastra Cloud project the env command should target.

Source

Thrown at packages/cli/src/commands/env/resolve-project.ts:29

export async function resolveProject(token: string, orgId: string, projectArg?: string): Promise<Project> {
  const projects = await fetchProjects(token, orgId);

  const wanted = process.env.MASTRA_PROJECT_ID ?? projectArg;
  if (wanted) {
    const project = projects.find(proj => proj.id === wanted || proj.name === wanted || proj.slug === wanted);
    if (!project) {
      throw new Error(`Project not found: ${wanted}`);
    }
    return project;
  }

  const config = await loadProjectConfig(process.cwd());
  if (config?.projectId) {
    const project = projects.find(proj => proj.id === config.projectId);
    if (project) return project;
  }

  throw new Error(
    'No project specified. Pass --project <name|slug|id>, set MASTRA_PROJECT_ID, or run from a directory with a linked .mastra-project.json.',
  );
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the project explicitly: `mastra env vars pull --project <name|slug|id>`
2. Set MASTRA_PROJECT_ID in the environment (or CI secrets) to the project id
3. Link the directory to the project so .mastra-project.json is created (mastra project link / init flow), or copy a teammate's file
4. Run the command from the directory that already has .mastra-project.json
5. For CI, commit .mastra-project.json or inject MASTRA_PROJECT_ID in the workflow

Example fix

// before
mastra env vars pull
// Error: No project specified...
// after
mastra env vars pull --project my-project
// or: export MASTRA_PROJECT_ID=prj_1234

import { existsSync, readFileSync } from 'node:fs';
const linked = existsSync('.mastra-project.json')
  ? JSON.parse(readFileSync('.mastra-project.json', 'utf8'))
  : null;
if (!linked?.projectId && !process.env.MASTRA_PROJECT_ID && !process.argv.includes('--project')) {
  throw new Error('No Mastra project target: pass --project, set MASTRA_PROJECT_ID, or run inside a linked directory (.mastra-project.json).');
}

function hasProjectTarget(args: { project?: string }, env: NodeJS.ProcessEnv, linkedConfigFile: unknown): boolean {
  const linked = linkedConfigFile as { projectId?: string } | null;
  return Boolean(args.project || env.MASTRA_PROJECT_ID || linked?.projectId);
}

try {
  await runEnvCommand(argv);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('No project specified')) {
    console.error(`${err.message}\nTip: run \`mastra project link\` in this directory or export MASTRA_PROJECT_ID in CI.`);
    process.exitCode = 1;
    return;
  }
  throw err;
}

When it happens

Trigger: Running `mastra env ...` outside a linked project directory, in a fresh clone where .mastra-project.json was never created or is gitignored, with MASTRA_PROJECT_ID unset, and without passing --project.

Common situations: Running the command from the repo root instead of the directory linked to Mastra Cloud; CI environment missing the MASTRA_PROJECT_ID secret; .mastra-project.json deleted or ignored by .gitignore; teammate never ran the link step.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Project not found: ${wanted}
• Factory rule version is required.
• MISSING_ARGUMENT
• No environments found for this project. Deploy first with `m
• Multiple environments found (${slugs}). Specify one: mastra

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