# How to debug a generation run with sdkgen --debug

> Find the stage of an sdkgen run that dropped a generated class, from its debug log, its unified model and aontu model why, then fix the model line responsible.

Source: https://voxgig.com/howto/debug-a-generation-run-with-sdkgen-debug

- Audience: api-producer
- Level: advanced
- Languages: typescript, go
- Verified: 2026-11-22
- Published: 2026-11-21

## Short answer

In the project's .sdk folder, run npx voxgig-model model/sdk.aontu -g debug and compare three records with a good run: the entity files apidef writes to model/entity, the unified model in model/sdk.json, and jostraca's generate-entity log lines. The first record that differs names the stage. npx aontu model why <path> model/sdk.aontu then names the file and line that set the value. Fix that line, regenerate, and diff the file list against the last good tree.

---
## You will need

Node 22 or later, git, and an sdkgen project scaffolded with `npm create @voxgig/sdkgen` from an
OpenAPI 3 document. The comparisons need Java for Swagger Codegen and Go 1.26 or later for `ogen`
v1.25.0, which declares that release in its `go.mod`. Verified 2026-11-22 against Node 22.23.5, `@voxgig/sdkgen` 4.44.3 from `@voxgig/create-sdkgen` 0.31.9,
`ogen` v1.25.0 and Swagger Codegen 3.0.85.

The project is the Bookshelf document with `ts` and `go` targets. `record.sh` in the sample ran
each generator once and kept its logs, with clock times, epoch milliseconds, and absolute paths
replaced by placeholders such as `<work>`. The commands below read those records.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [git diff against the last good generation](https://git-scm.com/docs/git-diff) | Any generator, when the output is committed and a good run exists | It names the files that changed, but neither the stage nor the input that changed them | The diff is large and you need the cause |
| [`ogen` -loglevel debug](https://ogen.dev/docs/config/) | A Go client from `ogen`, where a skipped operation is the usual missing method | A skip is one INFO line, and an `ogen.yml` in the directory turns skipping on | You need the data a template received, which its flags do not print |
| [sdkgen -g debug with aontu model why](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/debug-generation.md) | An sdkgen project, where one unified model feeds every target | Three stages to compare by hand, and a dry run that still writes the SDK | Your generator reads the document directly, with no model to query |
| [Swagger Codegen -DdebugOperations](https://github.com/swagger-api/swagger-codegen/blob/v3.0.85/modules/swagger-codegen/src/main/java/io/swagger/codegen/v3/DefaultGenerator.java) | You need the exact data each API template received | One parsed operation per path at INFO, and no template data until a `logback.xml` file opens one logger | You need to know why an operation is absent, which the dump shows only by omission |

Voxgig maintains sdkgen. It is the subject of this page, and the `ogen` and Swagger Codegen rows say
where each reads more directly.

A git diff works with any generator, but it shows only which files moved. `ogen` stops on input it
cannot generate unless a config file tells it to skip, and then one log line carries the cause.
Swagger Codegen's operation dump is the most detailed record here once a `logback.xml` file lets it through,
and it is long. sdkgen alone has a model you can ask for provenance, at the price of three stages
to rule in or out first.

## Plant a fault with a known cause

The sample debugs a fault planted on purpose, so the answer is known before the search starts.
`record.sh` scaffolds the project, generates it, commits the result, and appends one line to
`.sdk/model/project.aontu`, the overlay the scaffold never overwrites:

```aontu title="fixture/planted.aontu"
main: kit: entity: book: active: false
```

Then it runs the model build at debug level, inside `.sdk`, as you would:

```bash
npx voxgig-model model/sdk.aontu -g debug
```

`-g` takes `trace`, `error`, `debug`, `info`, `warn` or `fatal`. Call `voxgig-model` directly,
because `npm run generate` runs it twice and a flag after `--` reaches only the second run.

## Compare the three stages with the last good run

Each stage leaves a record you can read. apidef writes one `.aontu` file per entity to
`.sdk/model/entity`, aontu unifies everything into `.sdk/model/sdk.json`, and jostraca logs a
`generate-entity` line for each entity it builds in each target. `stages.mjs` reads all three
from both runs.

```bash
node stages.mjs
```

```text output
the change: main: kit: entity: book: active: false

stage 1, apidef writes model/entity/book.aontu
  before: entity book, operations create list load remove update
  after:  the same file, byte for byte
stage 2, aontu unifies the model into model/sdk.json
  before: main.kit.entity.book.active = true
  after:  main.kit.entity.book.active = false
stage 3, jostraca builds the targets (generate-entity lines in the debug log)
  before: target go book, target ts book
  after:  none
output
  before: Book( on 2 lines of ts/src/BookshelfSDK.ts, 3 of go/core/bookshelf_sdk.go; ts/src/entity holds BookEntity.ts
  after:  Book( on 0 lines of ts/src/BookshelfSDK.ts, 0 of go/core/bookshelf_sdk.go; ts/src/entity holds BookEntity.ts
  pruned by the run after the change: .sdk/test/entity/book/BookTestData.json ts/test/definition.test.ts
```

Stage 1 is the same file in both runs, so apidef read the document as before. Stage 2 is where the
runs part. Stage 3 follows the model it was given, so jostraca is not the cause either. The output
lines show why the tree misled. The run deleted two files it no longer generated, with one INFO
line each, and kept `BookEntity.ts`, because sdkgen prunes a file only when the component that
owned it ran again.[^1] The scaffold's `check-drift.sh` says regeneration never deletes such a
file, which holds here for the entity files alone.

## Ask aontu which line set the value

The installed aontu has two `why` verbs. `aontu why <pkg>` explains a package dependency, and
`aontu model why <path> <file>` explains a value. The second evaluates the model sources without
running apidef or jostraca, and lists every contribution with its file, line, and column.

```text title="records/why.txt"
$.main.kit.entity.book.active = false
  1. false  <work>/bookshelf-sdk/.sdk/model/project.aontu:33:34
  2. *true  <work>/bookshelf-sdk/.sdk/node_modules/@voxgig/apidef/model/apidef.aontu:17:11  (spread)
```

The first contribution is the planted line. The second is apidef's default, a `*true` that a
spread gives every entity, and a plain `false` overrides a default. The
[aontu README](https://github.com/aontu-lang/aontu) lists `model why` beside `model get` as the
query and provenance verbs.

## Fix the line and compare the file list

Delete the planted line, run `npm run generate`, stage the tree with `git add --all`, and compare it
with the last good commit by file list, using `git diff --cached --name-status`:

```text title="records/fixed-staged-diff.txt"
M	.sdk/log/generated.jsonl
```

`Book()` is back in both targets, and so are the two pruned files. Only the generation log differs
from the good commit, on 4.44.3 and on 4.45.0, and `npm run check-drift` calls the committed fix
clean.

Stage before you compare when the bad run was committed. That commit deleted the two files from
the index, so git does not track the regenerated copies, and `git diff --name-status` against a
commit reads tracked paths only:

```text title="records/fixed-diff.txt"
M	.sdk/log/generated.jsonl
D	.sdk/test/entity/book/BookTestData.json
D	ts/test/definition.test.ts
```

`git status` lists the same two files as `??`, which is the hint that the `D` lines are about the
index, not the disk.

## Trace a missing method in two other generators

`ogen` has no unified model to query, so the sample gives it a missing method of its own: the
`createBook` request body moved to `application/xml`, which `ogen` v1.25.0 does not generate.
Swagger Codegen reads the Bookshelf document as it stands.

```bash
node dumps.mjs
```

```text output
ogen v1.25.0, -loglevel debug
  api.json:                  exit 0, methods CreateBook DeleteBook GetBook ListBooks UpdateBook
  api-xml.json, no ogen.yml: exit 1, Content type "application/xml" is unsupported.
  api-xml.json, ogen.yml:    exit 0, methods DeleteBook GetBook ListBooks UpdateBook
    missing: CreateBook
    Skipping operation at api-xml.json:32:15: unsupported content types: [application/xml]

Swagger Codegen 3.0.85, -DdebugOperations=true
  default logging:        0 lines after the Operation info header, 5 processOperation dumps before it
  with logback-debug.xml: 2075 lines after it, operations DefaultApi.createBook DefaultApi.deleteBook DefaultApi.getBook DefaultApi.listBooks DefaultApi.updateBook
```

With no config file, `ogen` stops, names the media type, and suggests
[`ignore_not_implemented`](https://ogen.dev/docs/config/). With an `ogen.yml` that sets it to
`all`, the run exits 0 without `CreateBook`, and one `Skipping operation` line points at the
`post` object on line 32 of the document. `-loglevel debug` adds `Found config file`, which
matters because `ogen` reads `ogen.yml` from the working directory unasked.[^2]

Swagger Codegen's `-v` turns on four debug properties, and `-DdebugOperations=true` turns on one.
At the default logging, that one prints each operation as parsed, the five `processOperation`
entries counted in the output, and the dump of what the templates received stops after its header line. In 3.0.85
that body goes to a logger held at `info`.[^3] A
[`logback.xml` configuration file](https://logback.qos.ch/manual/configuration.html), passed with
`-Dlogback.configurationFile`, lets it through:

```xml title="swagger/logback-debug.xml"
    <logger name="io.swagger" level="info"/>
    <logger name="io.swagger.v3.core.util.Json" level="debug"/>
```

The dump then lists every operation the API template received, each under its class name. A
missing operation shows up as an absence from that list, which you find by comparing it with the
document.

## Check it worked

```bash
node --test debug.test.mjs
```

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

Each test reads the records and fails if one of them changes. They cover where the runs part, the
line `model why` names, and the dry run's writes and deletions on both releases. They also cover
the files the planted run pruned and the fix brought back, and the output of the other two
generators. One test feeds each reader empty or broken input and
expects a refusal.

## When it goes wrong

The dry run writes the SDK. `voxgig-model --help` says that `--dryrun` performs "a dry run, where no
files are modified" and the scaffold's `check-drift.sh` says how to "inspect a model with no side
effects" with `npm run dry-generate`. On 4.44.3 and 4.45.0 both leave `model/sdk.json` alone,
rewrite files under `ts/` and `go/`, and delete the two files the planted model no longer generates:

```text title="records/dryrun.txt"
[hh:mm:ss.mmm] INFO: model/sdkgen           generate-prune       removed .sdk/test/entity/book/BookTestData.json, no longer generated
[hh:mm:ss.mmm] INFO: model/sdkgen           generate-prune       removed ts/test/definition.test.ts, no longer generated
```

The model build keeps the flag to itself: sdkgen's `makeBuild` takes the logger and the debug
level from the build, and not its dry-run flag. Commit before a debug run, and run `git checkout -- .` and `git clean -fd` afterwards.

The debug lines never appear. `npm run generate -- -g debug` passes the flag to the last command in
the script, `voxgig-model test/test.aontu`, so the SDK build logs at `info`. Run `voxgig-model` on
`model/sdk.aontu` yourself.

`doctor` reports a clean project. `npx voxgig-sdkgen doctor` printed `.sdk matches the scaffold (0
additive, 0 customized)` and exited 0 on the planted tree, and again after a hand edit to
`ts/src/BookshelfSDK.ts`. It compares `.sdk` with the scaffold, never the output with the model.
`npm run check-drift` regenerates from nothing and lists the stale `BookEntity.ts` as deleted.

## When not to do this

Do not fix the output tree. The hand edit to `BookshelfSDK.ts` was gone after the next generate,
and `doctor` said nothing about it while it was there. Do not commit a generation you have not
compared with the last good one. The commit records the files the bad run pruned as deleted, and
every later comparison has to account for that.

Skip the three-stage comparison when the tree is small and committed. `git diff` finds a missing
class faster, and sdkgen's model is then one more stage to rule out. `ogen` suits a reader who needs
only a Go client, because it reports a skipped operation against a line and column of the
document. Swagger Codegen suits a reader who must see the data each template received, which
sdkgen's debug level does not print per template.

## Related how-tos

- [Find which template produced a generated file](/howto/find-which-template-produced-a-generated-file)

- [Find hand edits in a generated SDK before you regenerate](/howto/find-hand-edits-before-regenerating)

- [Block a release when generated SDK files have drifted](/howto/block-a-release-when-generated-sdk-files-drift)

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

- [Shorten the regenerate loop while you edit a template](/howto/shorten-the-regenerate-loop-while-editing-templates)

## Last verified

Verified 2026-11-22 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen`
4.44.3, `@voxgig/apidef` 8.32.4, `@voxgig/model` 12.0.2, aontu 0.76.3, jostraca 0.42.0, `ogen`
v1.25.0 built by Go 1.26, and Swagger Codegen 3.0.85 on OpenJDK 21. The dry run, the round trip and `doctor` ran
again on `@voxgig/sdkgen` 4.45.0. Each generator ran once, in `record.sh`, and every output block
is what the command preceding it printed from those records.

[^1]: The rule is the comment on `pruneGenerated`, at line 257 of
[`dist/helpers/generated.js`](https://unpkg.com/@voxgig/sdkgen@4.44.3/dist/helpers/generated.js) in
4.44.3 and 4.45.0. A run deletes each recorded file it did not emit "whose scope ran again" from
the disk. It keeps a file "whose scope did not run (a target or a phase switched off)" as it is. The planted run
logged no `generate-entity` line, so the components that write the entity's own files never ran,
and their files stayed.

[^2]: With no `--config`, `loadConfig` in [`ogen`'s
v1.25.0 command](https://github.com/ogen-go/ogen/blob/v1.25.0/cmd/ogen/main.go) tries `ogen.yml`,
`ogen.yaml`, `.ogen.yml` and `.ogen.yaml` in the working directory, in that order, and reads the
first it finds. Both the find and the absence of one are logged at debug level, so a run at the
default level does not say which file, if any, it read.

[^3]: The chain has three links. `DefaultGenerator` logs the header and hands the operations to
`Json.prettyPrint`. In [swagger-core
2.2.55](https://github.com/swagger-api/swagger-core/blob/v2.2.55/modules/swagger-core/src/main/java/io/swagger/v3/core/util/PrettyPrintHelper.java),
the release packed in the jar, that method passes the text to `PrettyPrintHelper.emit`, which logs
it at debug on the `Json` class's logger. The `logback.xml` at the root of the 3.0.85 jar sets
`io.swagger` to `info`, although the CLI module's [own
copy](https://github.com/swagger-api/swagger-codegen/blob/v3.0.85/modules/swagger-codegen-cli/src/main/resources/logback.xml)
at the same tag says `debug`.