Diagnostics

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

[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

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