mastra-ai/mastra · error · ApiCliError

SERVER_UNREACHABLE

SERVER_UNREACHABLE

Error message

Could not connect to target server

What it means

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'.

Source

Thrown at packages/cli/src/commands/api/target.ts:75

    }
    return { baseUrl: options.url, headers, timeoutMs, apiPrefix };
  }

  if (isObservabilityPath(path)) {
    return resolvePlatformServiceTarget(OBSERVABILITY_URL, customHeaders, timeoutMs);
  }

  if (isLearningPath(path)) {
    return resolvePlatformServiceTarget(LEARNING_URL, customHeaders, timeoutMs, { includeOrganization: true });
  }

  if (await canReachLocal(timeoutMs, fetchFn, apiPrefix)) {
    return { baseUrl: LOCAL_URL, headers: customHeaders, timeoutMs, apiPrefix };
  }

  const config = await loadProjectConfig(process.cwd());
  if (!config) {
    throw new ApiCliError('SERVER_UNREACHABLE', 'Could not connect to target server');
  }

  try {
    const token = await getToken();
    const projects = await fetchServerProjects(token, config.organizationId);
    const project = projects.find(
      candidate => candidate.id === config.projectId || candidate.slug === config.projectSlug,
    );
    const baseUrl = project?.instanceUrl;

    if (!baseUrl) {
      throw new ApiCliError('PLATFORM_RESOLUTION_FAILED', 'Could not resolve platform deployment URL', {
        projectId: config.projectId,
        projectSlug: config.projectSlug,
      });
    }

    return {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Start the local server: `mastra dev`, then retry
2. Pass an explicit target: `--target https://your-deployment.example.com` with any auth headers
3. Run the command from the project root that contains the Mastra project config (or create it via `mastra init`)
4. If the server runs on a non-default local port/prefix, set --target/--api-prefix explicitly instead of relying on local detection

Example fix

// before (no server running, no config)
mastra api agents list
// after
mastra dev &
mastra api agents list

async function canReach(url: string) {
  try { const r = await fetch(url); return r.ok || r.status < 500; } catch { return false; }
}
if (!(await canReach(localUrl)) && !hasProjectConfig(process.cwd())) {
  console.error('Start `mastra dev` or pass --target <url>');
}

function hasTarget(opts: { target?: string; projectConfig?: unknown }): opts is { target: string } { return typeof opts.target === 'string' || opts.projectConfig != null; }

try { await runApiCommand(cmd, args); } catch (e) { if (String(e).includes('SERVER_UNREACHABLE')) { console.error('Start `mastra dev` or pass --target'); } else throw e; }

When it happens

Trigger: 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`).

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• ${err instanceof Error ? err.message : String(err)}\nYou can
• HTTP_ERROR
• REQUEST_TIMEOUT
• Failed to fetch logs: ${error.detail}
• Failed to stream logs: ${resp.status} — ${text}

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