vercel/ai · error · HarnessCapabilityUnsupportedError

just-bash sandboxes run in-process and cannot expose a port

Error message

just-bash sandboxes run in-process and cannot expose a port URL. Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.

What it means

The just-bash sandbox runs entirely in-process (a simulated bash environment) and therefore has no networking layer capable of exposing a reachable port URL. getPortEndpoint thus always throws HarnessCapabilityUnsupportedError, directing users to a hosted sandbox provider for port/bridge features.

Source

Thrown at packages/sandbox-just-bash/src/just-bash-network-sandbox-session.ts:54

  constructor(input: { sandbox: Sandbox; ownsLifecycle: boolean }) {
    super(input.sandbox);
    this.ownsLifecycle = input.ownsLifecycle;
    this.id = randomUUID();
    this.defaultWorkingDirectory = input.sandbox.bashEnvInstance.getCwd();
  }

  readonly ports: ReadonlyArray<number> = [];

  restricted(): SandboxSession {
    return new JustBashSandboxSession(this.sandbox);
  }

  getPortEndpoint = async (_options: {
    port: number;
    protocol?: 'http' | 'https' | 'ws';
  }): Promise<HarnessV1PortEndpoint> => {
    throw new HarnessCapabilityUnsupportedError({
      harnessId: JUST_BASH_PROVIDER_ID,
      message:
        'just-bash sandboxes run in-process and cannot expose a port URL. ' +
        'Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.',
    });
  };

  /**
   * @deprecated Use `getPortEndpoint` instead.
   */
  getPortUrl = async (options: {
    port: number;
    protocol?: 'http' | 'https' | 'ws';
  }): Promise<string> => {
    return (await this.getPortEndpoint(options)).url;
  };

  stop = async (): Promise<void> => {

View on GitHub (pinned to 69428b1f8b)

Solutions

Use a hosted sandbox such as @ai-sdk/sandbox-vercel when you need port endpoints
Check capability support before calling getPortEndpoint
Keep just-bash for filesystem/command simulation only and run servers elsewhere
Catch HarnessCapabilityUnsupportedError and fall back to a hosted provider

Example fix

// before
const session = justBash({ ... });
const endpoint = await session.getPortEndpoint({ port: 3000 });
// after
const session = vercelSandbox({ ... });
const endpoint = await session.getPortEndpoint({ port: 3000 });

Defensive patterns

Strategy: fallback

Validate before calling

const supportsPortEndpoint = providerId !== 'just-bash';
if (!supportsPortEndpoint) {
  throw new Error('Select a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for port endpoints');
}

Type guard

function isCapabilityUnsupported(e) {
  return typeof e === 'object' && e !== null && e.constructor?.name === 'HarnessCapabilityUnsupportedError';
}

Try / catch

try {
  endpoint = await session.getPortEndpoint({ port: 3000 });
} catch (e) {
  if (e.constructor?.name === 'HarnessCapabilityUnsupportedError') {
    session = await createHostedSandbox(); // fallback
    endpoint = await session.getPortEndpoint({ port: 3000 });
  } else throw e;
}

Prevention

Treat just-bash as a filesystem/command simulator only — never expect networking
Check harness capabilities before choosing a sandbox provider
Abstract sandbox creation so hosted providers can be swapped in when ports are needed

When it happens

Trigger: Calling getPortEndpoint({ port }) on a session created by @ai-sdk/sandbox-just-bash — regardless of options — always throws.

Common situations: Harness adapters that assume all sandbox providers support port endpoints; testing code that starts an HTTP server inside just-bash and expects a URL to fetch; swapping sandbox providers without checking capabilities.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/ea4457f9ac6f438a. Report an issue: GitHub.