Reference

Diagnostics

Reference for Kubb's diagnostic codes, the stable codes Kubb prints when a build fails, with causes and fixes.

When a build fails, Kubb prints a diagnostic with a stable code, the message, the location in your document, and a suggested fix. The CLI leads with the code and lists the details below it:

Terminal

text

[KUBB_REF_NOT_FOUND]: Could not find a definition for #/components/schemas/Pet.
  at: #/components/schemas/Pet
  fix: Add the schema under components.schemas, or fix the $ref.
  see: https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found

Severity

The severity tints the [CODE] tag.

Severity	Color	Effect
`error`	red	Fails the run with a non-zero exit code.
`warning`	yellow	Reported, does not fail the run.
`info`	blue	Advisory, does not fail the run.

Input

Code	Severity	Summary
`KUBB_INPUT_NOT_FOUND`	error	The file set as `input` could not be read.
`KUBB_INPUT_REQUEST_FAILED`	error	A URL set as `input` answered with a 4xx or 5xx status.
`KUBB_INPUT_UNREACHABLE`	error	A URL set as `input` never answered.
`KUBB_INPUT_REQUIRED`	error	An adapter was configured without an `input`.
`KUBB_LEGACY_INPUT`	error	`input` uses the v4 `{ path }` / `{ data }` wrapper.

Configuration

Code	Severity	Summary
`KUBB_PLUGIN_NOT_FOUND`	error	A required plugin is missing from the config.
`KUBB_ADAPTER_REQUIRED`	error	An action needs an adapter but none is configured.
`KUBB_PATH_TRAVERSAL`	error	A resolved path escaped the output directory.
`KUBB_CLEAN_ROOT`	error	`output.clean` would delete the project root instead of only the generated code.
`KUBB_INVALID_PLUGIN_OPTIONS`	error	A plugin was configured with options that cannot be honored.

OpenAPI

Code	Severity	Summary
`KUBB_INVALID_DOCUMENT`	error	The resolved `input` declares no `openapi` or `swagger` version.
`KUBB_REF_NOT_FOUND`	error	A `$ref` could not be resolved in the document.
`KUBB_INVALID_SERVER_VARIABLE`	error	A server variable value is not allowed by its `enum`.
`KUBB_UNSUPPORTED_FORMAT`	warning	A schema `format` has no specific type mapping, so it falls back to the base type.
`KUBB_DEPRECATED`	info	A referenced schema or operation is marked `deprecated`.

Plugins

These carry whatever a plugin reports through its generator context (ctx.error, ctx.warn, ctx.info), attributed to the plugin that reported it.

Code	Severity	Summary
`KUBB_PLUGIN_FAILED`	error	A plugin threw while generating, or reported an error.
`KUBB_PLUGIN_WARNING`	warning	A plugin reported a non-fatal warning.
`KUBB_PLUGIN_INFO`	info	A plugin reported an informational message.
`KUBB_BARREL_DUPLICATE_EXPORT`	error	Two files in the same barrel directory export the same name.

Output pipeline

The formatter, linter, and post-generate hooks run after generation. A failure in any of them becomes a diagnostic that fails the run.

Code	Severity	Summary
`KUBB_FORMAT_FAILED`	error	The formatter pass over the generated files failed.
`KUBB_LINT_FAILED`	error	The linter pass over the generated files failed.
`KUBB_POST_GENERATE_FAILED`	error	A post-generate `output.postGenerate` command exited non-zero.

Other

Code	Severity	Summary
`KUBB_UNKNOWN`	error	An error without a specific code.

Bookkeeping

These are not problems. They carry run metadata, never fail the build, and feed the CLI's summary and notices rather than the diagnostic log.

Code	Severity	Summary
`KUBB_PERFORMANCE`	info	A plugin's elapsed time. The run total is the sum of these.
`KUBB_UPDATE_AVAILABLE`	info	A newer Kubb version is available on npm.

Machine-readable output

kubb generate --reporter json prints a stable report to stdout. The output is a JSON array with one report per config, so a single-config run still prints [ ... ]. CI can read diagnostics without scraping the terminal:

Report

json

[
  {
    "name": "",
    "status": "failed",
    "plugins": { "passed": 2, "failed": ["plugin-zod"], "total": 3 },
    "counts": { "errors": 1, "warnings": 0, "infos": 0 },
    "filesCreated": 0,
    "durationMs": 312,
    "output": "/project/src/gen",
    "timings": [{ "plugin": "plugin-ts", "durationMs": 84 }],
    "diagnostics": [
      {
        "code": "KUBB_REF_NOT_FOUND",
        "severity": "error",
        "message": "Could not find a definition for #/components/schemas/Pet.",
        "location": { "kind": "schema", "pointer": "#/components/schemas/Pet" },
        "help": "Add the schema under components.schemas, or fix the $ref. Run `kubb validate` to check the spec.",
        "docsUrl": "https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found"
      }
    ]
  }
]

Each config emits one report. counts totals the problem diagnostics by severity. timings lists per-plugin durations slowest first. name is the config name, empty when unnamed.

The exit code is unchanged: non-zero on any error. See --reporter for the other reporters.

Telemetry

Contributing

Diagnostics

Severity ​

Input ​

Configuration ​

OpenAPI ​

Plugins ​

Output pipeline ​

Other ​

Bookkeeping ​

Machine-readable output ​