Hmbown/CodeWhale · error · RuntimeCapabilityError

${options.capability}

${options.capability}

Error message

Runtime API capability '${options.capability}' is not available at ${method} ${path}

What it means

#rawRequest() maps HTTP 404, 405, and 501 responses to RuntimeCapabilityError when the request declared a capability (e.g. thread_event_stream, fleet endpoints). It signals that the connected runtime does not offer that API capability at the requested method/path. This is a version/feature mismatch, not a generic HTTP failure.

Solutions

Check err.code (the capability name) and upgrade the runtime to one that supports it.
Guard feature usage with try/catch on RuntimeCapabilityError and degrade gracefully.
Verify the request path/method matches the SDK's expected API surface (no custom base path rewriting in your proxy).

Example fix

// before
const runs = await client.listFleetWorkers(runId);
// after
try {
  const runs = await client.listFleetWorkers(runId);
} catch (err) {
  if (err instanceof RuntimeCapabilityError) return fallbackLocalWorkers();
  throw err;
}

Defensive patterns

Strategy: try-catch

Type guard

const isCapabilityMissing = (err) => err instanceof RuntimeCapabilityError;

Try / catch

try { return await client.listFleetWorkers(runId); } catch (err) { if (err instanceof RuntimeCapabilityError) { warn("runtime lacks capability " + err.code); return []; } throw err; }

Prevention

Version-gate feature usage: only call fleet/thread-stream APIs against runtimes that advertise them.
Map err.code values to feature flags in a central compatibility table.
Run an integration check against each deployed runtime version before enabling dependent features.

When it happens

Trigger: Calling a method like threadEvents, fleetEvents, getFleetRun, or listFleetWorkers against a runtime that returns 404/405/501 for that endpoint — e.g. fleet APIs invoked against a single-node runtime, or newer SDK methods against an older runtime.

Common situations: SDK and runtime version skew; feature flags disabled server-side; pointing the SDK at a gateway that only proxies a subset of routes.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/8ae51ffac18f671a. Report an issue: GitHub.

Appendix: source

Thrown at npm/runtime-sdk/index.js:185

      headers.set("authorization", `Bearer ${this.token}`);
    }
    const init = { method, headers };
    if (options.signal) init.signal = options.signal;
    if (options.redirect) init.redirect = options.redirect;
    if (options.body !== undefined) {
      headers.set("content-type", "application/json");
      init.body = JSON.stringify(options.body);
    }

    const response = await this.fetchImpl(new URL(path, this.baseUrl), init);
    if (response.ok) {
      return response;
    }

    const body = await readErrorBody(response);
    const errorOptions = { status: response.status, method, path, body };
    if (options.capability && [404, 405, 501].includes(response.status)) {
      throw new RuntimeCapabilityError(
        options.capability,
        `Runtime API capability '${options.capability}' is not available at ${method} ${path}`,
        errorOptions,
      );
    }
    throw new RuntimeApiError(
      `Runtime API request failed (${response.status}) for ${method} ${path}`,
      errorOptions,
    );
  }
}

export function createRuntimeClient(options = {}) {
  return new CodeWhaleRuntimeClient(options);
}

function normalizeBaseUrl(value) {
  return value.endsWith("/") ? value : `${value}/`;

View on GitHub (pinned to 433685b202)