Hmbown/CodeWhale · error · TypeError

Runtime API path segment must be a non-empty value

Error message

Runtime API path segment must be a non-empty value

What it means

Client-side TypeError thrown by the internal segment() helper before any network traffic when a runId or workerId argument is null, undefined, or trims to an empty string. Every id-taking method funnels its path segment through segment() for URL-encoding, so a blank id is rejected immediately as a programming error rather than producing a request like POST /v1/fleet/runs//start.

Source

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

    }
    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}/`;
}

function segment(value) {
  if (value === null || value === undefined || String(value).trim() === "") {
    throw new TypeError("Runtime API path segment must be a non-empty value");
  }
  return encodeURIComponent(String(value));
}

function fleetEventPath(path, options) {
  const query = new URLSearchParams();
  if (options.after !== undefined && options.after !== null && String(options.after) !== "") {
    query.set("after", String(options.after));
  }
  if (options.limit !== undefined && options.limit !== null) {
    query.set("limit", String(options.limit));
  }
  const encoded = query.toString();
  if (!encoded) {
    return path;
  }
  return `${path}${path.includes("?") ? "&" : "?"}${encoded}`;
}

View on GitHub (pinned to 8880682c63)

Solutions

1. Fix the call site to pass the actual string id — worker.id or the id returned by createFleetRun — not the object or an undefined variable
2. If the id comes from env/CLI input, validate it at your entry point and fail with a clear message naming the missing variable
3. Type the boundary as string (or a branded RunId/WorkerId type) so the mistake is caught at compile time

Example fix

// before
await client.startFleetRun(process.env.RUN_ID); // env unset -> undefined -> TypeError

// after
const runId = process.env.RUN_ID;
if (typeof runId !== "string" || runId.trim() === "") {
  throw new TypeError("RUN_ID must be set to an existing fleet run id");
}
await client.startFleetRun(runId);

function assertRuntimeId(label, value) {
  if (typeof value !== "string" || value.trim() === "") {
    throw new TypeError(`${label} must be a non-empty id (received ${JSON.stringify(value)})`);
  }
}

// before every call:
assertRuntimeId("runId", runId);
await client.startFleetRun(runId);

function isRuntimeId(value) {
  return typeof value === "string" && value.trim() !== "";
}

When it happens

Trigger: Calling getFleetRun, startFleetRun, stopFleetRun, replayFleetEvents, fleetEvents or listFleetWorkers with an undefined runId; calling getFleetWorker, interruptWorker, stopWorker or restartWorker with null, '' or whitespace workerId (e.g. a typo'd destructuring or an unset env var).

Common situations: Passing process.env.RUN_ID when it was never set (undefined); destructuring { id } from a createFleetRun response whose shape differs from expectation; passing the whole worker object instead of worker.id; an empty string flowing from CLI parsing.

Related errors

• Runtime API capability '${options.capability}' is not availa
• Runtime API request failed (${response.status}) for ${method
• ${name} is unavailable in Workflow scripts: runs must be det
• new Date()/Date() is unavailable in Workflow scripts: runs m
• task(): expected an options object

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/e972ac9536d6bbd3. Report an issue: GitHub.