mastra-ai/mastra · error · ApiCliError

PLATFORM_RESOLUTION_FAILED

PLATFORM_RESOLUTION_FAILED

Error message

Could not resolve platform deployment URL

What it means

When falling back to the Mastra platform, resolveTarget loads the project config, authenticates, and looks up the project among fetchServerProjects results by projectId or projectSlug. If the matching project has no instanceUrl (or no project matched so project is undefined), it throws PLATFORM_RESOLUTION_FAILED with the projectId/projectSlug as details.

Source

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

  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 {
      baseUrl,
      headers: { Authorization: `Bearer ${token}`, ...customHeaders },
      timeoutMs,
      apiPrefix,
    };
  } catch (error) {
    if (error instanceof ApiCliError) throw error;
    throw new ApiCliError('PLATFORM_RESOLUTION_FAILED', 'Could not resolve platform deployment URL', {
      message: error instanceof Error ? error.message : String(error),
    });
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the projectId/projectSlug in your project config against the platform dashboard and update it to the current project
2. Ensure the deployment exists and is running so instanceUrl is assigned, then retry
3. Re-authenticate (getToken) if the token lacks access to the organization that owns the project
4. Regenerate the project config (re-init) if it was copied from another project and references stale identifiers

Example fix

// before (project config points at deleted project)
{ "projectId": "prj_abc" }
// after
{ "projectId": "prj_xyz", "projectSlug": "my-agent-app" }

const projects = await fetchServerProjects(token);
const match = projects.find(p => p.id === cfg.projectId || p.slug === cfg.projectSlug);
if (!match?.instanceUrl) throw new Error(`Project ${cfg.projectId ?? cfg.projectSlug} has no running deployment`);

function hasInstanceUrl(p: { instanceUrl?: string } | undefined): p is { instanceUrl: string } { return typeof p?.instanceUrl === 'string' && p.instanceUrl.length > 0; }

try { await runApiCommand(cmd, args); } catch (e) { if (String(e).includes('PLATFORM_RESOLUTION_FAILED')) { console.error('Check projectId/projectSlug in project config and that the deployment is live'); } else throw e; }

When it happens

Trigger: config.projectId/projectSlug reference a project that no longer exists, was renamed, or whose deployment hasn't been provisioned yet, so `project?.instanceUrl` is undefined.

Common situations: Deleting or renaming the project in the Mastra platform while the local config still points at the old id/slug; deployment still building (no instance URL yet); token scoped to an organization that doesn't contain the project; stale config copied from another repo.

Related errors

• Platform integration: missing required environment variable
• Platform integration: missing required config field(s): ${mi
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Auth0 domain and audience are required, please provide them

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