Orpc contract with z.file() input allways returns empty {}

[lexer21]

Environment

orpc@1.13.5

Reproduction

Clone the following fork https://github.com/lexer21/orpc and run the NestJS example app (playgrounds/nest/) afterwards go to the Scalar client, to the upload planet endpoint (http://localhost:3000/#tag/planets/POST/upload-planet) and under request body set it to binary and select a file. Send the test the request. On the backend the request validates succesfully, but the data returned from the array buffer is not the selected file but just the plain empty object {}. The name of the contract is uploadPlanet, the same happens also if i set inputStructure to detailed.

Describe the bug

Client should send the binary file, but instead just sends the a empty object when using z.file() for input

Additional context

No response

Logs

[dosubot]

This happens because orpc does not natively handle multipart/form-data uploads as JS File objects, which is what z.file() expects for validation. In Node.js/Bun environments, uploaded files from multipart requests are not automatically parsed as File instances, so the input ends up as an empty object or fails validation. To support file uploads with z.file(), you need to add custom middleware on the server to parse the multipart upload and construct a JS File object before passing it to z.file() for validation. There is currently no built-in multipart parser or automatic workaround for this in orpc; server-side file uploads require custom handling if you want to use z.file() validation. If you are making manual API calls (like from Postman or Scalar), switching from RPCHandler to OpenAPIHandler can help, as OpenAPIHandler is designed to support these scenarios better. For more details, see this discussion and workaround and related documentation.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[unnoq]

This is a Scalar bug. As you can see in the Network tab, it uploads the file with {} as the content, so seeing {} in the console log is expected.
Try the same request with curl and you'll see a different result.

[lexer21]

@dosu @unnoq i have also tried with curl like this:

curl http://localhost:3000/upload-planet \
  --request POST \
  --header 'Authorization: Bearer default-token' \
  -F "file=@./test.pdf"

But i recieve a different error: {"defined":false,"code":"BAD_REQUEST","status":400,"message":"Input validation failed","data":{"issues":[{"expected":"file","code":"invalid_type","path":[],"message":"Invalid input: expected file, received object"}]}}

My contract is defined like this in the example repo:

export const uploadPlanet = oc
  .route({
    method: 'POST',
    path: '/upload-planet',
    summary: 'Upload planets',
    tags: ['Planets'],
  })
  .input(z.file())

[dosubot]

This error happens because orpc does not automatically convert multipart/form-data uploads into JS File objects, which is what z.file() expects for validation. When you use curl with -F, the backend receives the file as a plain object (like a Buffer or stream), not a JS File, so validation fails with "expected file, received object" see details.

To fix this, you need to add custom server-side handling: intercept the multipart request, extract the file from FormData, and construct a JS File object before passing it to z.file() for validation. The recommended approach is to extend the body parser or add middleware that does this conversion. There’s a recent guide and example showing how to do this in orpc see example.

If you want a quick outline: intercept the request, parse FormData, extract the file, and create a new File instance (using the blob and filename). Then pass that File to your contract handler. This is required because Node.js and NestJS do not natively provide JS File objects from multipart uploads.

Let me know if you want a code snippet or more details on implementing this workaround.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[unnoq]

OpenAI

1️⃣ Raw binary as the entire request body (most common)

This sends the file exactly as-is in the body.

curl -X POST https://example.com/upload \
  --data-binary @file.bin \
  -H "Content-Type: application/octet-stream"

[lexer21]

Ok tnx it works now, thank you for your quick help, much appreciated!