No linked project found. Deploy first with `mastra server de

Error message

No linked project found. Deploy first with `mastra server deploy` or set MASTRA_PROJECT_ID.

What it means

Env commands must know which project's variables to read/write. resolveProjectId checks MASTRA_PROJECT_ID, then --project, then the linked .mastra-project.json (written by a previous deploy). If none yields a projectId it throws — it will not guess a project for env operations.

Source

Thrown at packages/cli/src/commands/server/env.ts:41

export async function resolveProjectId(
  opts: { config?: string; project?: string },
  auth?: { token: string; orgId: string },
): Promise<string> {
  const envProjectId = process.env.MASTRA_PROJECT_ID;
  if (envProjectId) return envProjectId;

  if (opts.project) {
    if (auth) {
      const projects = await fetchServerProjects(auth.token, auth.orgId);
      const match = projects.find(p => p.slug === opts.project || p.id === opts.project);
      if (match) return match.id;
    }
    return opts.project;
  }

  const config = await loadProjectConfig(process.cwd(), opts.config);
  if (!config?.projectId) {
    throw new Error('No linked project found. Deploy first with `mastra server deploy` or set MASTRA_PROJECT_ID.');
  }
  return config.projectId;
}

/* ------------------------------------------------------------------ */
/*  mastra server env list                                             */
/* ------------------------------------------------------------------ */

export async function envListAction(opts: { config?: string }) {
  const { token, orgId } = await resolveAuth();
  const projectId = await resolveProjectId(opts);

  const envVars = await getServerProjectEnv(token, orgId, projectId);
  const keys = Object.keys(envVars);

  if (keys.length === 0) {
    console.info('\nNo environment variables set.\n');
    return;

View on GitHub (pinned to 75dd419e61)

Solutions

Set MASTRA_PROJECT_ID in the environment
Pass --project <id-or-slug> to the env command
Run `mastra server deploy` once from this directory to create the .mastra-project.json link, then retry
cd into the package directory that contains .mastra-project.json

Example fix

// before
mastra server env set API_KEY secret
// after
mastra server env set API_KEY secret --project proj_456
# or
export MASTRA_PROJECT_ID=proj_456 && mastra server env set API_KEY secret

Defensive patterns

Strategy: validation

Validate before calling

import { readFile } from 'node:fs/promises';
// Preflight before env commands
export async function ensureProjectLinked(configPath = '.mastra-project.json') {
  if (process.env.MASTRA_PROJECT_ID) return;
  try {
    const cfg = JSON.parse(await readFile(configPath, 'utf-8'));
    if (cfg.projectId) return;
  } catch {}
  throw new Error('No linked project: set MASTRA_PROJECT_ID, pass --project, or deploy first.');
}

Type guard

function isLinkedConfig(cfg: unknown): cfg is { projectId: string } {
  return typeof cfg === 'object' && cfg !== null &&
    typeof (cfg as any).projectId === 'string' && (cfg as any).projectId.length > 0;
}

Try / catch

try {
  await exec('mastra server env list');
} catch (err) {
  if (err instanceof Error && err.message.includes('No linked project found')) {
    console.error('Deploy once from this directory, or pass --project / set MASTRA_PROJECT_ID.');
  }
  throw err;
}

Prevention

Deploy once from a directory before managing its env vars
Consider committing .mastra-project.json or recreating it in CI
Always pass --project in shared scripts
Run env commands from the linked package directory, not the repo root

When it happens

Trigger: Running `mastra server env list|set|unset|import` in a directory that was never deployed (no .mastra-project.json or it lacks projectId), with no MASTRA_PROJECT_ID env var and no --project flag.

Common situations: Fresh clone where .mastra-project.json was gitignored; managing env vars for a project before its first deploy; running from a monorepo root instead of the linked package directory; CI environment missing the MASTRA_PROJECT_ID secret.

Related errors

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