# How to debug why a generated SDK sends the wrong content type

> Capture the Content-Type a generated SDK sends, trace it to the OpenAPI document and the generator's choice, and fix it where regeneration keeps the fix.

Source: https://voxgig.com/howto/debug-wrong-content-type-from-generated-sdk

- Audience: api-producer
- Level: intermediate
- Languages: typescript, python
- Verified: 2026-11-19
- Published: 2026-11-19

## Short answer

To debug a wrong Content-Type from an sdkgen SDK, capture the header with mitmproxy in reverse mode or the SDK's own explain record, then read the rb entry of the operation in .sdk/model/entity. It shows the media type the model chose from requestBody.content. Correct it with body.media in the guide file, regenerate, and capture again. In the version run here, a form body also needs a hook to encode it.

---
## You will need

Node 22 or later, an OpenAPI 3 document, and a generated SDK whose calls fail with 415 or 400.
The capture step uses [mitmproxy](https://docs.mitmproxy.org/stable/concepts/modes/#reverse-proxy).
Verified 2026-11-19 against `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3, Swagger
Codegen 3.0.85, `openapi-typescript` 7.13.0, `openapi-fetch` 0.17.0, and mitmproxy 12.3.1. The API
here is a stand-in on the loopback interface. Its `POST /books` takes a form and answers 415 to
JSON, though `api.json` lists both, and it records the `Content-Type` of every request.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [hand-written fetch](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest_API/Using_FormData_Objects) | One or two calls, and you want to see every header you send | Each media type encoded by hand, and a multipart header you must leave to `fetch` | The API has many operations, or clients in several languages |
| [Kiota `--structured-mime-types`](https://learn.microsoft.com/en-us/openapi/kiota/using#--structured-mime-types--m) | You generate with Kiota and the API prefers a type other than JSON | One weighting for the whole document, so two operations cannot differ | One operation takes a form and another takes JSON |
| [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/python/api.mustache) | Its `typescript-fetch` client, which sends the first media type the document lists | A rule that differs by generator: the Python client prefers JSON, with `_content_type` per call | You cannot reorder the document, or need one rule everywhere |
| [openapi-typescript and openapi-fetch](https://openapi-ts.dev/openapi-fetch/api#url-encoded-body) | TypeScript, and each call site can name its own media type | JSON unless the call sets a header or a `bodySerializer`, repeated at every call site | The document should decide, not each caller |
| [sdkgen guide `body.media`](https://github.com/voxgig/apidef/blob/main/docs/reference/guide.md) | sdkgen generates the SDK and its model picked the wrong type from several | A corrected model that the generated runtime honors for JSON and raw bodies only | The API takes a form or multipart, which needs a hook besides |
| [Swagger Codegen templates](https://github.com/swagger-api/swagger-codegen/blob/3.0.0/docs/generators.md) | You generate with Swagger Codegen and can change the document it reads | No media type option, so the fix is the document or a template folder you maintain | The operation is multipart and the client is `typescript-fetch` |

Voxgig maintains sdkgen. It is one of six options here, not the recommendation.

Three layers can carry the fix. The document reaches every generator that reads it, but Swagger
Codegen and OpenAPI Generator read the same list differently. A generator override, Kiota's
weights or sdkgen's guide, leaves a document you may not own alone, and binds the fix to one
tool. A patch to generated code lasts until the next regeneration.

## Capture the header that went out

A reverse proxy needs no proxy setting and no certificate in the client. Start mitmproxy in
front of the API with a script that prints one line per request, and point the SDK's base URL at
the proxy.

```py title="capture.py"
def request(flow):
    sent = flow.request.headers.get("content-type", "(none)")
    print(flow.request.method, flow.request.path, "content-type:", sent, flush=True)
```

```bash
mitmdump -q -s capture.py --mode reverse:API_ORIGIN -p 8080
```

Run by hand in front of the stand-in, with the SDK as first generated and its `base` set to
`http://127.0.0.1:8080/v1`, the script printed `POST /v1/books content-type: application/json`.
The 415 agrees with it. [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type)
lets a server name the types it would have accepted in an `Accept` response header, and the
stand-in sends `application/x-www-form-urlencoded` there.[^1]

## Trace the choice to the document and the model

The header comes from the operation's `requestBody.content`, a map with one key for each media
type the API says it takes.

```json title="api.json"
"requestBody": { "required": true, "content": {
  "application/json": {
    "schema": { "$ref": "#/components/schemas/NewBook" } },
  "application/x-www-form-urlencoded": {
    "schema": { "$ref": "#/components/schemas/NewBook" } }
} },
```

A client sends one of them, so every generator has a rule for choosing. OpenAPI Generator's
TypeScript client sends the first key listed,[^2] Kiota weighs the types, and sdkgen prefers JSON
whenever the document offers it. sdkgen also writes its choice down, as the `rb` entry of the
operation in the entity model. `model.mjs` reads that entry from the model as first generated,
and again after the correction that follows.

```bash
node model.mjs
```

```text output
model-before/book.aontu
  create sends  application/json (kind json)
  alternatives  application/x-www-form-urlencoded
model-after/book.aontu
  create sends  application/x-www-form-urlencoded (kind form)
  alternatives  application/json
```

The correction is one line in `.sdk/model/guide/guide.aontu`, which generation reads and leaves
as you wrote it. The [model reference](https://github.com/voxgig/apidef/blob/main/docs/reference/model.md)
gives the rule it overrides.

```aontu title="guide.aontu"
guide: entity: book: path: "/books": op: create: body: media: "application/x-www-form-urlencoded"
```

## Capture again after you regenerate

Regenerate, then capture again, this time without a proxy. An sdkgen SDK records the request it
built when the call's control argument carries an `explain` object.

```js title="demo.mjs"
// The explain record is the SDK's own account of the request it built.
const ctrl = { explain: {} }
// A 415 rejects; the record and the stand-in's log say what happened.
await sdk.Book().create(BOOK, ctrl).catch(() => {})
const { headers, body } = ctrl.explain.fetchdef
```

```bash
node demo.mjs
```

```text output
book.create, model corrected
  the SDK built     content-type: application/json
                    body: {"author":"Jane Austen","published":1817,"title":"Persuasion"}
  the API received  content-type: application/json
  the API answered  415
```

The model changed, but the request did not. In the version run here, the generated runtime sets
the header for `json` and `raw` bodies only, in the TypeScript and Python targets alike, so a
`form` body still goes out as JSON. The corrected entry does reach the SDK, as
`ctx.point.body`, and a hook can act on it. `generate.sh` adds this one as a feature of the
project's own, under `.sdk`:

```ts title="feature/FormbodyFeature.ts"
// The request spec is built and not yet sent.
PreRequest(this: any, ctx: any) {
  const declared = ctx.point?.body
  const data = ctx.spec?.body
  if ('form' !== declared?.kind || null == data || 'object' !== typeof data) {
    return
  }

  const form = new URLSearchParams()
  for (const field of declared.fields ?? []) {
    if (Object.hasOwn(data, field.name) && null != data[field.name]) {
      form.append(field.name, String(data[field.name]))
    }
  }

  const headers = ctx.spec.headers
  for (const name of Object.keys(headers)) {
    if ('content-type' === name.toLowerCase()) {
      delete headers[name]
    }
  }
  headers['content-type'] = declared.media
  ctx.spec.body = form.toString()
}
```

With `feature: { formbody: { active: true } }` in the constructor, the same call goes through:

```bash
node demo.mjs
```

```text output
book.create, model corrected, formbody feature on
  the SDK built     content-type: application/x-www-form-urlencoded
                    body: author=Jane+Austen&published=1817&title=Persuasion
  the API received  content-type: application/x-www-form-urlencoded
  the API answered  201
```

## Fix the document for Swagger Codegen

Swagger Codegen has no option that selects a media type: `config-help` lists none for its
`typescript-fetch` or `python` generator. With both types listed, its TypeScript client assigns
the header twice, and the JSON assignment comes last.

```ts title="swagger-codegen/as-written/api.ts"
localVarHeaderParameter['Content-Type'] = 'application/x-www-form-urlencoded';

localVarHeaderParameter['Content-Type'] = 'application/json';
```

`swagger-demo.mjs` calls that client, then the one generated from `api-form.json`, which is
`api.json` with the JSON entry removed.

```bash
node swagger-demo.mjs
```

```text output
generated from api.json
  createBook   sent content-type: application/json                   answered 415
  uploadCover  sent content-type: application/x-www-form-urlencoded  answered 415
generated from api-form.json
  createBook   sent content-type: application/x-www-form-urlencoded  answered 201
```

Removing the entry fixes `createBook`. Reordering the entries does not: a run outside the sample
changed the header and left the body as JSON. `uploadCover` is the reverse failure, a
`multipart/form-data` operation sent URL-encoded, though the document lists that type alone. The
documented lever there is a template folder passed with `-t`. The Python client declares the multipart type
for that operation, and picks among several types with this rule:

```py title="swagger-codegen/python/api_client.py"
if 'application/json' in content_types or '*/*' in content_types:
    return 'application/json'
else:
    return content_types[0]
```

## Name the media type per call in `openapi-fetch`

`openapi-typescript` writes both media types into the type of `body`, and `openapi-fetch` reads no
document at run time. It serializes and labels every body as JSON unless the call says otherwise.
Its documentation gives two switches: a `Content-Type` header of
`application/x-www-form-urlencoded`, which makes the default serializer URL-encode the body, and a
[`bodySerializer`](https://openapi-ts.dev/openapi-fetch/api#bodyserializer) that returns a
`FormData`.

```bash
node fetch-demo.mjs
```

```text output
POST /books, body alone   sent content-type: application/json                   answered 415
POST /books, form header  sent content-type: application/x-www-form-urlencoded  answered 201
POST cover, FormData      sent content-type: multipart/form-data; boundary=...  answered 201
```

The fix lives at each call site, so two callers of one operation can disagree.

## Check it worked

Ten tests pin every row of those outputs against the stand-in.

```bash
node --test content-type.test.mjs
```

```text output
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

`# pass 10` includes the test that expects the body `author=Jane+Austen&published=1817&title=Persuasion`
and a 201 with the feature on. Remove the feature's `PreRequest` method and that test fails on
`application/json`.

## When it goes wrong

A multipart upload answers 400 after you set the header yourself. A `Content-Type` of
`multipart/form-data` written by hand replaces the one `fetch` would write, and the boundary
parameter goes with it. [RFC 7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.1) makes
that parameter required,[^3] so the server cannot find the parts. Leave the header unset.

```bash
node pitfall.mjs
```

```text output
Content-Type left to fetch  sent content-type: multipart/form-data; boundary=...  answered 201
Content-Type set by hand    sent content-type: multipart/form-data                answered 400
```

The fix disappears after a release. It was an edit to a generated file, and the next
regeneration overwrote it. Move it to the document, the generator's override, or a hook the
generator keeps.

The SDK's record and the capture disagree. A record made inside the SDK shows the request it
handed to `fetch`. A header that `fetch` completes, such as the multipart boundary, shows only on
the wire.

## When not to do this

Do not patch the generated request code, in any generator. The patch works once and teaches
nobody where the choice was made.

Do not stop at sdkgen's guide when the API takes a form. As run here, the correction changes the
model and not the request, and the hook is code you maintain for every target you ship. Swagger
Codegen is the better choice when you can correct the document and the body is a URL-encoded
form. Remove one entry, and its client sends the form with no code from you. `openapi-fetch` is
the better choice when callers must choose per call, or the body is multipart, where a
`FormData` serializer is the whole fix.

Do not correct the client when the server is the one at fault. If the document says the API
takes JSON, and you own the API, accepting JSON repairs every SDK already published.

Do not trust a green regeneration. Capture the header again.

## Related how-tos

- [Debug a query string the API rejects](/howto/debug-a-query-string-the-api-rejects)

- [Reduce a failing SDK call to a minimal reproduction](/howto/minimal-reproduction-of-a-failing-sdk-call)

- [Rename a generated SDK method without editing the output](/howto/rename-generated-methods-without-editing-output)

- [Preview a regeneration as a diff before writing files](/howto/preview-a-regeneration-as-a-diff)

- [Generate your first SDK with sdkgen](/howto/first-sdk-with-sdkgen)

## Last verified

Verified 2026-11-19 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3,
Swagger Codegen 3.0.85, `openapi-typescript` 7.13.0, and `openapi-fetch` 0.17.0. Every output
block is what the command preceding it printed. The generation runs are not repeated by those
commands: their output is committed, and `generate.sh` records them. mitmproxy 12.3.1 was run by
hand with `capture.py`, and its line is quoted in the text. The Python target, the reordered
document, and the Kiota 1.38.0 and OpenAPI Generator 7.27.0 runs behind their table rows were
run outside the sample.

[^1]: [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type)
spends two sentences on what a 415 should carry. For an unsupported content coding, the
`Accept-Encoding` response header "ought to be used," in its words. For an unsupported media type,
the `Accept` response header "can be used," and no more than that. The media type got the weaker
verb.

[^2]: The first key listed is a property of the file more than of the document.
[RFC 8259](https://www.rfc-editor.org/rfc/rfc8259.html#section-4) defines a JSON object as an
unordered collection of name and value pairs, and observes that parsing libraries differ on
whether they show member order to the software calling them. A generator that follows the order
is reading something the format declines to promise.

[^3]: [RFC 7578](https://www.rfc-editor.org/rfc/rfc7578.html) replaced RFC 2388 in July 2015, and
its list of changes says that "boundary" became a required parameter of the `Content-Type`. The
parts of the body are delimited by a line break, two hyphens, and that value, so a header without
it describes a body nobody can cut up.