OpenAPI spec generation fails (Error 500) with outputStructure: "detailed"

[theoludwig]

Environment

Node.js v24.12.0, orpc v1.12.3

Reproduction

https://github.com/theoludwig/orpc-repro

Describe the bug

A procedure like the following (notably with outputStructure: "detailed"):

callback: publicProcedure
.route({
  method: "GET",
  path: "/whatever",
  successStatus: 302,
  outputStructure: "detailed",
})
.handler(async () => {
  return {
    headers: {
      location: "/some-url",
    },
  }
})

Will make it so that going to OpenAPI documentation, will returns a HTTP Error 500:

{"defined":false,"code":"INTERNAL_SERVER_ERROR","status":500,"message":"Internal server error"}

As soon as I put in comments the procedure, the documentation work again.
I tried also, by returning something else that headers.location, like a body, but same issue.

Additional context

No response

Logs

No logs in the Node.js terminal, so no clue what is going on.

[dosubot]

The 500 error during OpenAPI spec generation with outputStructure: "detailed" happens because orpc expects the output schema to be an object with optional properties: status (a literal number between 200–399), headers (an object schema), and body (any type). If the schema doesn't match this structure—especially if headers isn't defined as an object schema—OpenAPIGenerator throws an error, resulting in the 500 you see in docs generation (source).

To fix this, make sure your procedure's output schema is explicitly defined as an object with a headers property that itself is an object schema. For example, using zod:

import { z } from "zod";

publicProcedure
  .route({
    method: "GET",
    path: "/whatever",
    successStatus: 302,
    outputStructure: "detailed",
  })
  .output(
    z.object({
      headers: z.object({
        location: z.string(),
      }),
      // Optionally include body or status if needed
    })
  )
  .handler(async () => ({
    headers: { location: "/some-url" },
  }));

Recent improvements (PR #1178) have expanded support for unions and intersections in output schemas, and added more robust handling for detailed output structures. If you upgrade to a newer orpc version, you may benefit from better error messages and broader schema support.

If you need to return only headers, your output schema must still be an object with a headers property defined as an object schema. Even if you don't use body or status, they should be optional in the schema.

Let me know if you need a more specific schema example for your use case.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.