{"record":{"id":"00509940423e9067","repo":"decolua/9router","slug":"transform-returned-an-unexpected-shape","errorCode":null,"errorMessage":"transform returned an unexpected shape","messagePattern":"transform returned an unexpected shape","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/lib/pxpipe/loader.js","lineNumber":67,"sourceCode":"    return mod.transformAnthropicMessages;\n  } catch {\n    return null;\n  }\n}\n\n// Health self-test: run a tiny synthetic Claude request through the transformer.\n// A healthy module parses it and answers with a machine-readable reason.\nexport async function selfTest() {\n  const startedAt = Date.now();\n  const { module: mod } = await loadPxpipe();\n  const body = new TextEncoder().encode(JSON.stringify({\n    model: \"claude-fable-5\",\n    max_tokens: 16,\n    messages: [{ role: \"user\", content: \"ping\" }],\n  }));\n  const result = await mod.transformAnthropicMessages({ body, model: \"claude-fable-5\" });\n  if (!result || typeof result.applied !== \"boolean\" || !(result.body instanceof Uint8Array)) {\n    throw new Error(\"transform returned an unexpected shape\");\n  }\n  return { ok: true, reason: result.reason, durationMs: Date.now() - startedAt };\n}\n","sourceCodeStart":49,"sourceCodeEnd":71,"githubUrl":"https://github.com/decolua/9router/blob/90b52e06ffd666b7929554211474d01588f6b1f8/src/lib/pxpipe/loader.js#L49-L71","documentation":"Thrown by selfTest after invoking the loaded pxpipe transformAnthropicMessages on a tiny synthetic Claude request. The transform is required to return an object with `applied` (boolean) and `body` (Uint8Array); anything else means the module loaded and exposed the function but violated its output contract, so the health check fails rather than passing malformed data downstream.","triggerScenarios":"transformAnthropicMessages returns null/undefined (e.g. it failed internally and returned nothing), returns a plain object missing `applied`, or returns body as a Buffer/string/ArrayBuffer instead of a Uint8Array — detected only when selfTest (the Test button / health probe) runs.","commonSituations":"A pxpipe version bump changed the return shape (e.g. returning Buffer, or {ok, data} instead of {applied, body, reason}); the transform swallows an error and returns undefined; a hand-patched/local build of pxpipe diverging from the documented contract; running selfTest against a module built for a different runtime (returning ArrayBuffer under Node).","solutions":["Log the actual return value of transformAnthropicMessages in selfTest to see what shape came back, then compare with the expected {applied: boolean, body: Uint8Array, reason} contract.","Upgrade or downgrade pxpipe to the version matching this app's contract (use Repair, which cache-busts via ?v=version).","Fix the pxpipe transform to always return {applied, body: Uint8Array, reason} — e.g. wrap Buffer results: new Uint8Array(buffer).","Ensure the transform re-encodes the body even when nothing is applied (applied:false path must still return a Uint8Array body).","Rebuild the pxpipe module if a local patch or bundler step altered the return type, then re-run the self-test."],"exampleFix":"// before (pxpipe transform returning Buffer)\nreturn { applied: changed, body: Buffer.from(out), reason };\n// after\nreturn { applied: changed, body: new Uint8Array(out), reason };","handlingStrategy":"type-guard","validationCode":"const result = await transform({ body, model });\nif (!result || typeof result.applied !== \"boolean\" || !(result.body instanceof Uint8Array)) {\n  throw new Error(\"transform returned an unexpected shape\");\n}","typeGuard":"function isTransformResult(r) {\n  return !!r && typeof r.applied === \"boolean\" && r.body instanceof Uint8Array;\n}\n// tolerate Buffer under Node:\nconst ok = isTransformResult(r) || (r && typeof r.applied === \"boolean\" && Buffer.isBuffer(r.body));","tryCatchPattern":"try {\n  const report = await selfTest();\n} catch (e) {\n  if (e.message === \"transform returned an unexpected shape\") {\n    console.error(\"pxpipe contract violation — reinstall matching version or fix transform return to {applied:boolean, body:Uint8Array}\");\n  } else throw e;\n}","preventionTips":["Always return a plain object {applied: boolean, body: Uint8Array, reason} from the transform, even on the not-applied path.","Convert Buffers/ArrayBuffers to Uint8Array before returning (new Uint8Array(buf)).","Never return undefined/null from an internal failure — throw instead so the loader reports the real error.","Run selfTest after every pxpipe install/upgrade to catch contract drift immediately.","Add a unit test for the transform's return shape in the pxpipe package itself."],"tags":["pxpipe","self-test","schema-validation","api-contract"],"backgroundTag":"transform-result-shape-mismatch","analyzedSha":"90b52e06ffd666b7929554211474d01588f6b1f8","analyzedAt":"2026-08-30T21:05:45.952Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}