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. The severity tints the [CODE] tag: red for error, yellow for warning, blue for info.

[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

Codes

Find the code printed by Kubb below. Each entry explains the cause and the fix.

Errors

An error fails the run with a non-zero exit code.

KUBB_ADAPTER_REQUIRED: Adapter required

An action needs an adapter but none is configured.

Set adapter in your config, for example adapterOas(). Standard defineConfig supplies the default OpenAPI adapter, so this catalog code is not currently emitted for an omitted adapter.

KUBB_BARREL_DUPLICATE_EXPORT: Duplicate barrel export

Two files in the same barrel directory export the same name. The barrel keeps the first export and drops the rest, so the generated code still parses, but the run is marked failed.

Rename the colliding declarations, change the resolver, or separate their output directories. A type and a value may share a name.

KUBB_CLEAN_ROOT: Clean targets the project root

output.clean removes generated code before a build. Kubb stops the build instead of wiping your project when output.path resolves to the project root or a parent of it, which would delete kubb.config and every source file.

Use a generated subdirectory such as ./src/gen. Disable output.clean if it contains hand-written files. Kubb rejects cleaning the project root or a parent directory.

KUBB_FORMAT_FAILED: Format failed

The formatter pass over the generated files failed. Formatting runs after generation. The files are written, but the run is marked failed.

Check that the formatter is installed and its config is valid. Run it against the output directory to inspect the error, or change output.format.

KUBB_INCOMPATIBLE_DEPENDENCY: Incompatible dependency

A plugin's dependencies record sets a version range, and the configured plugin's meta.version falls outside it. Kubb skips the check when the dependency has no meta.version.

Install a version of the dependency inside the range, or a version of the dependent plugin that supports the installed dependency.

KUBB_INCOMPATIBLE_EXTENSION: Incompatible extension

A plugin sets meta.compatibility.kubb or meta.compatibility.node to a range the running Kubb or Node.js version does not satisfy. Kubb checks this before any plugin runs.

Upgrade Kubb or Node.js to a version in the range, or install a version of the plugin that supports your current Kubb and Node.js.

KUBB_INPUT_NOT_FOUND: Input not found

The file set as input (or passed as kubb generate PATH) could not be read. The OpenAPI adapter checks the path before parsing, so the run stops here instead of failing later with a vague read error.

Check that the file exists and is readable. Use a path relative to kubb.config.ts, an absolute path, or a full URL for a remote spec.

KUBB_INPUT_REQUEST_FAILED: Input request failed

A URL set as input answered with a 4xx or 5xx status instead of the OpenAPI document. The server was reached, so either the URL is wrong or the endpoint refused to serve the document.

Fetch the URL with curl and confirm it serves the OpenAPI document. For a protected document, download it and use the local file. Check server logs for a 5xx response. This also applies to remote $ref requests.

KUBB_INPUT_REQUIRED: Input required

An adapter is configured but no input was provided, so there is nothing to parse.

Set input to a file path, URL, inline JSON/YAML spec, or parsed document. If merging documents, provide at least one input.

KUBB_INPUT_UNREACHABLE: Input unreachable

A URL set as input never answered, so the request failed before a status came back.

Start the server and check its host and port. Fetch the URL from the machine running Kubb. Connect to any required VPN or proxy, or use a downloaded spec. The message includes the connection failure reason.

KUBB_INVALID_DOCUMENT: Invalid document

The document resolved from input declares neither openapi nor swagger, so the adapter has nothing to read it as.

Use a document declaring openapi or swagger. Pass the document itself rather than a wrapper. Missing versions fail even when validation is disabled.

KUBB_INVALID_PLUGIN_OPTIONS: Invalid plugin options

A plugin was given options that cannot be honored together. The main case is output.mode resolving to 'file' while a group option is also set, or, for @kubb/plugin-fetch/@kubb/plugin-axios, while sdk.mode: 'tag' is set. Both pair a single-file output with an option that only makes sense split across several files, so the build stops instead of producing a layout the options do not describe.

Single-file output cannot use group or sdk.mode: 'tag'. Remove grouping, use sdk.mode: 'flat', or write to a directory. A file extension in output.path implies file mode unless you explicitly select directory mode.

KUBB_INVALID_SERVER_VARIABLE: Invalid server variable

A server variable resolves to a value that its enum does not allow.

Choose a variable value allowed by its enum, correct the default, or update the enum to match the server.

KUBB_LEGACY_INPUT: Legacy input shape

input is a { path } or { data } wrapper. v4 used it to point at a document, and v5 takes the value directly.

Replace input: { path: './spec.yaml' } with input: './spec.yaml', or input: { data: spec } with input: spec.

KUBB_LINT_FAILED: Lint failed

The linter pass over the generated files failed. Linting runs after generation. The files are written, but the run is marked failed.

Check that the linter is installed and configured. Run it manually against the output. Adjust rules for generated files or change output.lint.

KUBB_MISSING_DEPENDENCY: Missing dependency

A plugin lists another plugin in its dependencies record without optional: true, and the config does not include it. A dependencies array only orders plugins and never raises this code.

Install the missing plugin and add it to plugins in kubb.config.ts.

KUBB_NO_CONTEXT: No plugin context

A kubb/kit composable such as useKubb() or addGenerator() ran outside setup and kubb:plugin:setup. Composables read the context of the plugin being set up, so outside setup there is no plugin to apply them to. The message names the composable that was called.

Call the composable inside setup or kubb:plugin:setup. Code that setup awaits also works, because the context survives an await. Generators and later hooks run after setup, so they cannot use composables.

KUBB_PATH_TRAVERSAL: Path traversal

A resolved output path escaped the output directory. Kubb refuses to write outside output.path, so a crafted spec or a misconfigured group.name cannot drop files anywhere on disk.

Keep generated paths within output.path and resolver file.path overrides within the project root. Reject .. and path separators in names from the spec or group.name.

KUBB_PLUGIN_FAILED: Plugin failed

A plugin threw while generating, or reported an error through ctx.error. The diagnostic is attributed to the plugin and fails the run.

Check the plugin options and the schema or operation named in the message. Report reproducible plugin bugs with a spec fragment. The diagnostic preserves an underlying error as its cause. For structured errors, plugin authors can use Diagnostics.Error or Diagnostics.report.

KUBB_PLUGIN_NOT_FOUND: Plugin not found

A plugin requires another plugin that is not in the config.

Install the required plugin and add it to plugins, or remove its dependent plugin. Order does not matter. The adapter reads OpenAPI in v5, so do not add @kubb/plugin-oas.

KUBB_POST_GENERATE_FAILED: Post-generate command failed

A post-generate command (output.postGenerate) exited with a non-zero status. These commands run after generation. The files are written, but the run is marked failed.

Run the command manually from the project root. Check the binary, spelling, and configuration. These commands run after formatting and linting.

KUBB_REF_NOT_FOUND: Reference not found

A $ref points at a definition that does not exist in the document.

Add the missing definition or correct the $ref. Run kubb validate before generation. Bundle documents with external references when needed.

KUBB_UNKNOWN: Unknown error

A fallback for an error that does not yet carry a specific diagnostic code.

Run kubb generate --reporter file for a log under .kubb/, or use --verbose. Inspect the message and stack. Report unclear failures with the message and Environment: block. Unclassified errors have no suggested fix or docs URL in CLI output.

Warnings

A warning is reported and the run continues.

KUBB_INVALID_SPEC: Invalid spec

The document does not pass OpenAPI schema validation. Kubb reports each problem and keeps generating, but the output can be incomplete or wrong. @kubb/adapter-oas checks this when validate is true, the default.

Fix the reported problem in the spec. Run kubb validate to list every error with its location. Set validate: false on the adapter to skip the check.

KUBB_PLUGIN_WARNING: Plugin warning

A plugin reported a non-fatal warning through ctx.warn.

Read the message and adjust the input or plugin options as needed. Plugin authors can use Diagnostics.report for a stable code and source pointer.

KUBB_UNSUPPORTED_FORMAT: Unsupported format

A schema's format is not one Kubb maps to a specific type, so it falls back to the base type.

Use a supported format, omit it if the base type is sufficient, or map it through a custom parser or plugin.

Info

An info diagnostic is advisory and never fails the run.

KUBB_DEPRECATED: Deprecated

A referenced schema or operation is marked deprecated.

Move away from the deprecated definition when possible. Generation continues unchanged, and the notice may recur on each run.

KUBB_PERFORMANCE: Performance

Records a plugin's elapsed time. Kubb collects one per plugin during a build.

This bookkeeping code is not printed as a terminal diagnostic. Run kubb generate --verbose to inspect plugin timings. The reported duration sums generation time and excludes config loading, formatting, linting, and post-generate hooks.

KUBB_PLUGIN_INFO: Plugin info

A plugin reported an informational message through ctx.info.

No action is required. The plugin name and message appear in the summary and JSON report. Plugin authors can use Diagnostics.report for a stable code and source pointer.

KUBB_UPDATE_AVAILABLE: Update available

A newer Kubb version is published on npm than the one running.

Update Kubb and your project plugins through your package manager.

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:

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