{"record":{"id":"6079265e42a88b61","repo":"mastra-ai/mastra","slug":"server-unreachable","errorCode":"SERVER_UNREACHABLE","errorMessage":"Could not connect to target server","messagePattern":"Could not connect to target server","errorType":"error_code","errorClass":"ApiCliError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/api/target.ts","lineNumber":75,"sourceCode":"    }\n    return { baseUrl: options.url, headers, timeoutMs, apiPrefix };\n  }\n\n  if (isObservabilityPath(path)) {\n    return resolvePlatformServiceTarget(OBSERVABILITY_URL, customHeaders, timeoutMs);\n  }\n\n  if (isLearningPath(path)) {\n    return resolvePlatformServiceTarget(LEARNING_URL, customHeaders, timeoutMs, { includeOrganization: true });\n  }\n\n  if (await canReachLocal(timeoutMs, fetchFn, apiPrefix)) {\n    return { baseUrl: LOCAL_URL, headers: customHeaders, timeoutMs, apiPrefix };\n  }\n\n  const config = await loadProjectConfig(process.cwd());\n  if (!config) {\n    throw new ApiCliError('SERVER_UNREACHABLE', 'Could not connect to target server');\n  }\n\n  try {\n    const token = await getToken();\n    const projects = await fetchServerProjects(token, config.organizationId);\n    const project = projects.find(\n      candidate => candidate.id === config.projectId || candidate.slug === config.projectSlug,\n    );\n    const baseUrl = project?.instanceUrl;\n\n    if (!baseUrl) {\n      throw new ApiCliError('PLATFORM_RESOLUTION_FAILED', 'Could not resolve platform deployment URL', {\n        projectId: config.projectId,\n        projectSlug: config.projectSlug,\n      });\n    }\n\n    return {","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/api/target.ts#L57-L93","documentation":"resolveTarget first tries the local Mastra server (canReachLocal). If that fails and no project config exists in the current directory (loadProjectConfig returns null), there is no target at all, so the CLI throws SERVER_UNREACHABLE with 'Could not connect to target server'.","triggerScenarios":"Running an api command with no Mastra dev server running locally, no --target flag, and no mastra project config (e.g. executing from outside a Mastra project directory or before `mastra init`).","commonSituations":"Forgetting to start the dev server (`mastra dev`); running the CLI from the wrong directory so no project config is found; a custom port the CLI doesn't probe; typo'd/expired --target; firewall blocking localhost.","solutions":["Start the local server: `mastra dev`, then retry","Pass an explicit target: `--target https://your-deployment.example.com` with any auth headers","Run the command from the project root that contains the Mastra project config (or create it via `mastra init`)","If the server runs on a non-default local port/prefix, set --target/--api-prefix explicitly instead of relying on local detection"],"exampleFix":"// before (no server running, no config)\nmastra api agents list\n// after\nmastra dev &\nmastra api agents list","handlingStrategy":"validation","validationCode":"async function canReach(url: string) {\n  try { const r = await fetch(url); return r.ok || r.status < 500; } catch { return false; }\n}\nif (!(await canReach(localUrl)) && !hasProjectConfig(process.cwd())) {\n  console.error('Start `mastra dev` or pass --target <url>');\n}","typeGuard":"function hasTarget(opts: { target?: string; projectConfig?: unknown }): opts is { target: string } { return typeof opts.target === 'string' || opts.projectConfig != null; }","tryCatchPattern":"try { await runApiCommand(cmd, args); } catch (e) { if (String(e).includes('SERVER_UNREACHABLE')) { console.error('Start `mastra dev` or pass --target'); } else throw e; }","preventionTips":["Start the dev server before running api commands","Run CLI commands from the Mastra project root (config must exist)","Use explicit --target for remote/non-default deployments","Health-check the target URL before invoking commands in scripts"],"tags":["network","cli","connectivity"],"backgroundTag":"connection-refused","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}