How-to › Operate integrations in production

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.

Audience
API producer
Level
advanced
Topic
Debug an integration
Languages
TypeScript and Go
Verified

You change one line under .sdk/model, regenerate, and Book() is gone from the TypeScript and Go clients. The model build exits 0 with no warning, and ts/src/entity/BookEntity.ts is still on disk. Three stages ran between your edit and the output, apidef, aontu and jostraca, and any of them could have dropped the entity.

What you get

You will end up with the stage that dropped the entity, the model line that switched it off, and a regenerated tree checked against the last good one. This is for you if your sdkgen output changed while the OpenAPI document stayed the same.

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
git diff against the last good generationAny generator, when the output is committed and a good run existsIt names the files that changed, but neither the stage nor the input that changed themThe diff is large and you need the cause
ogen -loglevel debugA Go client from ogen, where a skipped operation is the usual missing methodA skip is one INFO line, and an ogen.yml in the directory turns skipping onYou need the data a template received, which its flags do not print
sdkgen -g debug with aontu model whyAn sdkgen project, where one unified model feeds every targetThree stages to compare by hand, and a dry run that still writes the SDKYour generator reads the document directly, with no model to query
Swagger Codegen -DdebugOperationsYou need the exact data each API template receivedOne parsed operation per path at INFO, and no template data until a logback.xml file opens one loggerYou 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:

main: kit: entity: book: active: false

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

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.

node stages.mjs
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.

$.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 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:

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:

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.

node dumps.mjs
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. 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, passed with -Dlogback.configurationFile, lets it through:

    <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

node --test debug.test.mjs
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:

[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.

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.

Footnotes

  1. The rule is the comment on pruneGenerated, at line 257 of 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. ↩︎ Back to text

  2. With no --config, loadConfig in ogen’s v1.25.0 command 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. ↩︎ Back to text

  3. The chain has three links. DefaultGenerator logs the header and hands the operations to Json.prettyPrint. In swagger-core 2.2.55, 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 at the same tag says debug. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.