Introduction

This error usually appears when an API endpoint is supposed to receive a multipart request that contains both a file and a JSON part, but the JSON part is described or sent incorrectly. The server then sees the part as application/octet-stream or some other unsupported media type instead of application/json.

The fix is usually not "change the whole endpoint to octet-stream." The real fix is to define the multipart parts correctly in OpenAPI and bind them correctly on the server side.

Why the Error Happens

In a multipart request, each part has its own content type. That means the file part might be application/pdf, while a metadata part should be application/json.

If the OpenAPI schema does not describe the JSON part properly, generated clients and server frameworks often fall back to treating it as raw bytes. On the server, that becomes an unsupported application/octet-stream request part.

Describe the Multipart Request Correctly in OpenAPI

For OpenAPI 3, define one multipart object and describe both parts explicitly:

1requestBody:
2  required: true
3  content:
4    multipart/form-data:
5      schema:
6        type: object
7        required:
8          - metadata
9          - file
10        properties:
11          metadata:
12            $ref: '#/components/schemas/UploadMetadata'
13          file:
14            type: string
15            format: binary
16      encoding:
17        metadata:
18          contentType: application/json

The key line is the encoding entry for metadata. That tells OpenAPI tooling that the metadata part is JSON, not arbitrary binary data.

A matching schema might look like this:

1components:
2  schemas:
3    UploadMetadata:
4      type: object
5      required:
6        - title
7      properties:
8        title:
9          type: string
10        category:
11          type: string

Bind the Parts Correctly in Spring

On the server side, use @RequestPart for the JSON object and for the file:

1import org.springframework.http.MediaType;
2import org.springframework.http.ResponseEntity;
3import org.springframework.web.bind.annotation.PostMapping;
4import org.springframework.web.bind.annotation.RequestPart;
5import org.springframework.web.bind.annotation.RestController;
6import org.springframework.web.multipart.MultipartFile;
7
8@RestController
9public class UploadController {
10
11    @PostMapping(path = "/documents", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
12    public ResponseEntity<Void> upload(
13            @RequestPart("metadata") UploadMetadata metadata,
14            @RequestPart("file") MultipartFile file) {
15
16        System.out.println(metadata.getTitle());
17        System.out.println(file.getOriginalFilename());
18        return ResponseEntity.ok().build();
19    }
20}

If you use @RequestBody for the JSON piece, or if the part is sent without an application/json content type, Spring often cannot deserialize it the way you expect.

Test the Request Outside the Generated Client

Before blaming the OpenAPI generator, send a manual curl request that sets the part type clearly:

curl -X POST http://localhost:8080/documents \
  -F 'metadata={"title":"Quarterly report","category":"finance"};type=application/json' \
  -F '[email protected];type=application/pdf'

If this works, the server contract is probably fine and the generated client is the next place to inspect. If it fails, the endpoint or OpenAPI definition is still wrong.

What to Check in Generated Clients

Generated clients sometimes serialize the JSON part as a string or byte array without the correct per-part content type. In that case:

• inspect the actual multipart boundary payload
• confirm the metadata part has Content-Type: application/json
• confirm the file part is still sent as binary

The top-level request should be multipart/form-data, but individual parts still need their own media types.

Common Pitfalls

• Describing the whole request as application/json even though it contains a file.
• Omitting the encoding section for the JSON multipart part in OpenAPI.
• Using @RequestBody instead of @RequestPart for multipart JSON in Spring.
• Assuming application/octet-stream is correct for the JSON metadata part.
• Debugging only the top-level Content-Type instead of the part-level content types.

Summary

• A multipart request can contain both a file part and a JSON part, but each part needs the correct media type.
• In OpenAPI, describe the JSON part in the multipart schema and set its encoding to application/json.
• In Spring, bind multipart JSON with @RequestPart, not a normal JSON request body.
• Use a manual curl request to separate server problems from generated-client problems.
• When you see application/octet-stream not supported, inspect the individual multipart part headers first.