mastra-ai/mastra · error

Sandbox provider "${sandbox.provider}" does not support netw

Error message

Sandbox provider "${sandbox.provider}" does not support networking (public port URLs), which is required for sandbox deploys.

What it means

Sandbox deploys need public port URLs to route traffic to the running Mastra server. deployToSandbox checks supportsNetworking(sandbox) after starting the sandbox and refuses to continue when the provider implementation lacks the networking capability (no networking.getPortUrl support).

Source

Thrown at deployers/sandbox/src/engine.ts:68

    env = {},
    studio = false,
    healthCheckPath = '/api',
    healthCheckTimeoutMs = 60_000,
    healthCheckIntervalMs = 1_000,
    installCommand = 'npm install --omit=dev',
    logger = noopLogger,
  } = options;

  if (!existsSync(join(dir, 'index.mjs'))) {
    throw new Error(`No index.mjs found in "${dir}" — did the build succeed?`);
  }

  // 1. Start (providers handle create-or-resume by identity, e.g. sandbox name).
  logger.info(`Starting ${sandbox.provider} sandbox...`);
  await sandbox.start?.();

  if (!supportsNetworking(sandbox)) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support networking (public port URLs), ` +
        `which is required for sandbox deploys.`,
    );
  }
  if (!sandbox.executeCommand) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`,
    );
  }

  const url = await sandbox.networking.getPortUrl(port);
  if (!url) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" did not expose a public URL for port ${port}. ` +
        `Make sure the port is declared when constructing the sandbox (e.g. \`ports: [${port}]\`).`,
    );
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a networking-capable provider for sandbox deploys
2. Implement the networking capability (networking.getPortUrl) in your custom provider
3. Declare ports in the provider config so URLs can be exposed
4. Route local-only sandboxes through a different deploy path (not deployToSandbox)

Example fix

// before
const sandbox = new ExecOnlySandbox();
await deployToSandbox(sandbox, options);
// after
const sandbox = new CloudSandbox({ ports: [8788] });
await deployToSandbox(sandbox, options);

// check capability before deploying
if (typeof sandbox.networking?.getPortUrl !== 'function') {
  console.warn('provider cannot expose public URLs; use a networking-capable sandbox');
}

function supportsNetworking(s: Sandbox): s is Sandbox & Required<Pick<Sandbox, 'networking'>> {
  return typeof (s as any).networking?.getPortUrl === 'function';
}

When it happens

Trigger: Calling deployToSandbox with a sandbox provider object that does not implement networking (e.g. a local/exec-only provider) — the feature-detection helper supportsNetworking returns false.

Common situations: Using a provider built for local development only with the remote deploy engine; switching deploy targets from cloud to a minimal custom provider; older/custom provider integrations predating the networking API.

Related errors

• Sandbox provider "${sandbox.provider}" did not expose a publ
• Sandbox provider "${sandbox.provider}" does not support exec
• Sandbox provider "${sandbox.provider}" did not expose a publ
• Sandbox provider "${sandbox.provider}" does not support netw
• Woke sandbox but the Mastra server did not become healthy at

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