{"record":{"id":"dce1af77995bfb6f","repo":"mastra-ai/mastra","slug":"no-linked-project-found-deploy-first-with-mastra","errorCode":null,"errorMessage":"No linked project found. Deploy first with `mastra server deploy` or set MASTRA_PROJECT_ID.","messagePattern":"No linked project found\\. Deploy first with `mastra server deploy` or set MASTRA_PROJECT_ID\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/server/env.ts","lineNumber":41,"sourceCode":"export async function resolveProjectId(\n  opts: { config?: string; project?: string },\n  auth?: { token: string; orgId: string },\n): Promise<string> {\n  const envProjectId = process.env.MASTRA_PROJECT_ID;\n  if (envProjectId) return envProjectId;\n\n  if (opts.project) {\n    if (auth) {\n      const projects = await fetchServerProjects(auth.token, auth.orgId);\n      const match = projects.find(p => p.slug === opts.project || p.id === opts.project);\n      if (match) return match.id;\n    }\n    return opts.project;\n  }\n\n  const config = await loadProjectConfig(process.cwd(), opts.config);\n  if (!config?.projectId) {\n    throw new Error('No linked project found. Deploy first with `mastra server deploy` or set MASTRA_PROJECT_ID.');\n  }\n  return config.projectId;\n}\n\n/* ------------------------------------------------------------------ */\n/*  mastra server env list                                             */\n/* ------------------------------------------------------------------ */\n\nexport async function envListAction(opts: { config?: string }) {\n  const { token, orgId } = await resolveAuth();\n  const projectId = await resolveProjectId(opts);\n\n  const envVars = await getServerProjectEnv(token, orgId, projectId);\n  const keys = Object.keys(envVars);\n\n  if (keys.length === 0) {\n    console.info('\\nNo environment variables set.\\n');\n    return;","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/server/env.ts#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nmastra server env set API_KEY secret\n// after\nmastra server env set API_KEY secret --project proj_456\n# or\nexport MASTRA_PROJECT_ID=proj_456 && mastra server env set API_KEY secret","handlingStrategy":"validation","validationCode":"import { readFile } from 'node:fs/promises';\n// Preflight before env commands\nexport async function ensureProjectLinked(configPath = '.mastra-project.json') {\n  if (process.env.MASTRA_PROJECT_ID) return;\n  try {\n    const cfg = JSON.parse(await readFile(configPath, 'utf-8'));\n    if (cfg.projectId) return;\n  } catch {}\n  throw new Error('No linked project: set MASTRA_PROJECT_ID, pass --project, or deploy first.');\n}","typeGuard":"function isLinkedConfig(cfg: unknown): cfg is { projectId: string } {\n  return typeof cfg === 'object' && cfg !== null &&\n    typeof (cfg as any).projectId === 'string' && (cfg as any).projectId.length > 0;\n}","tryCatchPattern":"try {\n  await exec('mastra server env list');\n} catch (err) {\n  if (err instanceof Error && err.message.includes('No linked project found')) {\n    console.error('Deploy once from this directory, or pass --project / set MASTRA_PROJECT_ID.');\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["cli","config","project-linking"],"backgroundTag":"missing-project-link","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}