Diagnostics

When a build fails, Kubb prints a diagnostic. It carries 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

[KUBB_REF_NOT_FOUND] @kubb/plugin-zod: 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_REQUIRED	error	An adapter was configured without an input.

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_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). Each one is 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.

Output pipeline

The formatter, linter, and post-generate hooks run after generation. A failure in any of them becomes a diagnostic and 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 and never fail the build. The CLI uses them for the summary and notices, not 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

[
  {
    "name": "",
    "status": "failed",
    "plugins": { "passed": 2, "failed": ["@kubb/plugin-zod"], "total": 3 },
    "counts": { "errors": 1, "warnings": 0, "infos": 0 },
    "filesCreated": 0,
    "durationMs": 312,
    "output": "/project/src/gen",
    "timings": [{ "plugin": "@kubb/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. It is non-zero on any error. See --reporter for the other reporters.