{"record":{"id":"e972ac9536d6bbd3","repo":"Hmbown/CodeWhale","slug":"runtime-api-path-segment-must-be-a-non-empty-value","errorCode":null,"errorMessage":"Runtime API path segment must be a non-empty value","messagePattern":"Runtime API path segment must be a non-empty value","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"npm/runtime-sdk/index.js","lineNumber":179,"sourceCode":"    }\n    throw new RuntimeApiError(\n      `Runtime API request failed (${response.status}) for ${method} ${path}`,\n      errorOptions,\n    );\n  }\n}\n\nexport function createRuntimeClient(options = {}) {\n  return new CodeWhaleRuntimeClient(options);\n}\n\nfunction normalizeBaseUrl(value) {\n  return value.endsWith(\"/\") ? value : `${value}/`;\n}\n\nfunction segment(value) {\n  if (value === null || value === undefined || String(value).trim() === \"\") {\n    throw new TypeError(\"Runtime API path segment must be a non-empty value\");\n  }\n  return encodeURIComponent(String(value));\n}\n\nfunction fleetEventPath(path, options) {\n  const query = new URLSearchParams();\n  if (options.after !== undefined && options.after !== null && String(options.after) !== \"\") {\n    query.set(\"after\", String(options.after));\n  }\n  if (options.limit !== undefined && options.limit !== null) {\n    query.set(\"limit\", String(options.limit));\n  }\n  const encoded = query.toString();\n  if (!encoded) {\n    return path;\n  }\n  return `${path}${path.includes(\"?\") ? \"&\" : \"?\"}${encoded}`;\n}","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/8880682c63083a91624de936797efa3ce9e498fd/npm/runtime-sdk/index.js#L161-L197","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["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","If the id comes from env/CLI input, validate it at your entry point and fail with a clear message naming the missing variable","Type the boundary as string (or a branded RunId/WorkerId type) so the mistake is caught at compile time"],"exampleFix":"// before\nawait client.startFleetRun(process.env.RUN_ID); // env unset -> undefined -> TypeError\n\n// after\nconst runId = process.env.RUN_ID;\nif (typeof runId !== \"string\" || runId.trim() === \"\") {\n  throw new TypeError(\"RUN_ID must be set to an existing fleet run id\");\n}\nawait client.startFleetRun(runId);","handlingStrategy":"validation","validationCode":"function assertRuntimeId(label, value) {\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new TypeError(`${label} must be a non-empty id (received ${JSON.stringify(value)})`);\n  }\n}\n\n// before every call:\nassertRuntimeId(\"runId\", runId);\nawait client.startFleetRun(runId);","typeGuard":"function isRuntimeId(value) {\n  return typeof value === \"string\" && value.trim() !== \"\";\n}","tryCatchPattern":null,"preventionTips":["Validate env/CLI-sourced ids once at your entry point with a clear variable name in the message","Type fleet calls as (client, runId: string) so object-vs-id mistakes surface at compile time","Destructure ids from API responses defensively (run?.id) and fail loudly when absent","Remember this throws before any network traffic — it always indicates your own call site, not the server"],"tags":["runtime-api","sdk","validation","typeerror","programmer-error"],"backgroundTag":null,"analyzedSha":"8880682c63083a91624de936797efa3ce9e498fd","analyzedAt":"2026-08-16T11:31:27.956Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}