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

Error message

Sandbox provider "${sandbox.provider}" does not support networking (public port URLs).

What it means

getDeployment() resolves a sandbox and needs a publicly reachable port URL; this requires the sandbox provider to support networking. When supportsNetworking(sandbox) is false (the provider has no networking capability / getPortUrl), the library throws instead of failing later with an opaque undefined URL. It means the chosen sandbox provider cannot expose public port URLs at all.

Source

Thrown at deployers/sandbox/src/client/index.ts:118

    },
    // Resolved lazily — reading logs requires a running sandbox anyway.
    logs: async (lines?: number) => tailServerLog(sandbox, await resolveRemoteDir(sandbox, options.remoteDir), lines),
  });

  if (!wake) {
    // Resolve without starting the sandbox (starting can resume billing).
    const url = supportsNetworking(sandbox) ? await sandbox.networking.getPortUrl(port) : null;
    if (!url) {
      return handle(null, 'stopped');
    }
    const healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });
    return handle(url, healthy ? 'running' : 'stopped');
  }

  await sandbox.start?.();

  if (!supportsNetworking(sandbox)) {
    throw new Error(`Sandbox provider "${sandbox.provider}" does not support networking (public port URLs).`);
  }
  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}]\`).`,
    );
  }

  // Some providers (e.g. Vercel) restore the filesystem but not processes on
  // resume, while others (e.g. E2B) resume processes too — relaunch the server
  // from the recorded launch script only when it is not answering.
  let healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: 3_000, intervalMs: 1_000 });
  if (!healthy) {
    const remoteDir = await resolveRemoteDir(sandbox, options.remoteDir);
    await killPreviousServer(sandbox, remoteDir);
    await launchServer(sandbox, remoteDir);
    healthy = await waitForHealthy(url, { path: healthCheckPath, timeoutMs: healthCheckTimeoutMs, intervalMs: 1_000 });

View on GitHub (pinned to 75dd419e61)

Solutions

Use a sandbox provider that supports networking (declares ports and implements networking.getPortUrl).
Declare the needed ports when constructing the sandbox (ports: [3000]) so a networking-capable provider can expose URLs.
If the provider intentionally has no networking, obtain the URL through that provider's own mechanism instead of getDeployment()'s port URL path.
Update the provider registration/config so sandbox.provider points at the intended networking-capable provider.

Example fix

// before
const sandbox = createLocalSandbox({ provider: 'local' }); // no networking support
await getDeployment({ sandbox, port: 3000 });
// after
const sandbox = createCloudSandbox({ provider: 'cloud', ports: [3000] });
await getDeployment({ sandbox, port: 3000 });

Defensive patterns

Strategy: validation

Validate before calling

if (typeof (sandbox as any).networking?.getPortUrl !== 'function') {
  throw new Error(`Provider "${sandbox.provider}" cannot expose public port URLs; choose a networking-capable provider`);
}

Type guard

function supportsNetworking(sandbox: { networking?: unknown }): sandbox is typeof sandbox & { networking: { getPortUrl: (port: number) => Promise<string | undefined> } } {
  return typeof (sandbox as any).networking?.getPortUrl === 'function';
}

Try / catch

try {
  const dep = await getDeployment({ sandbox, port });
} catch (err) {
  if ((err as Error).message.includes('does not support networking')) {
    console.error(`Provider ${sandbox.provider} lacks public URLs; switch provider or use its native URL mechanism.`);
  } else throw err;
}

Prevention

Declare ports: [port] when constructing a sandbox so networking-capable providers can expose URLs.
Verify provider capabilities (supportsNetworking) at startup, before deploying.
When writing custom providers, implement the networking capability including getPortUrl.
Keep provider choice consistent across environments; document which providers support public URLs.

When it happens

Trigger: Calling getDeployment() for a sandbox whose provider lacks a networking capability — e.g. a local/in-process or exec-only provider — while requesting a port URL, after sandbox.start() succeeds.

Common situations: Switching a project from a cloud sandbox provider to a local provider (or vice versa) and forgetting the local one doesn't expose public URLs; constructing a custom provider without implementing networking.getPortUrl; tests using a mock provider without networking.

Related errors

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