Diagnostics

Every build analyzes your API description (an OpenAPI or AsyncAPI document) and your SDK configuration together, and reports everything the generator had to skip, guess, or degrade. Each finding is graded, and you decide which grades fail the build.

A successful build tells you the SDK compiled. It does not tell you the SDK is complete. Generation is forgiving by design: an operation no resource places is simply absent, a schema with no properties becomes an untyped value, a pagination scheme nothing references is dead configuration. Each of those produces a perfectly valid SDK that is quietly missing something you meant to ship, and diagnostics are how you find out.

How it works

Diagnostics run as part of every build. Almost every check runs after the document and configuration are loaded and compiled, and before any target is generated. One check, Target/InvalidGeneratedCode, runs after a target is generated and before its files are written; see After generation.

The full report is part of the build output, whether the build passed or failed, so it is there in the build logs to read either way.

Two properties are worth knowing about, because they decide how much a finding can be trusted:

• Most findings are facts, not guesses. The loader, the configuration coercion, and the compiler report what they actually did. A Config/StaleEndpoint finding is not a second opinion about your configuration — it is the compiler saying that it skipped the method.
• Rules and generation share one implementation. Where a rule has to work something out for itself — the name a model would be generated under, whether a response media type can be decoded, which resource a schema belongs to — it calls the same helpers generation calls. A finding cannot drift away from what the generator actually does, because there is only one answer for both of them to read.

A rule that crashes never takes your build down with it. The engine isolates each rule, skips the one that failed, and records it as Internal/RuleCrash.

After generation

Target/InvalidGeneratedCode is the generator checking its own output. After a target is generated, and before its files are written, the generator runs any compile check that target has. Today only the Go target has one: it catches a generated sample that assigns a struct field a type its declaration does not have.

A finding is graded and suppressed like any other, and it applies to one target only:

• At its default error grade, that target fails. Its files are not written, so it does not ship from this build, and the build is reported as failed. Every other target is still generated and written as usual.
• The finding means the generator produced code that does not compile. No edit to your configuration or your API description is the fix: contact Scalar support with the API description that triggers it.
• Suppressing the finding, or grading it below your failOn level, lets the target through, and the code that does not compile is written and shipped. Do that only to unblock a release while the generator is fixed, scoped to the one target with a { "target": "go", "reason": "…" } entry.

Anatomy of a finding

Every finding carries the same fields, whichever rule produced it:

Rendered, one finding reads like this:

[WARN] Config/StaleEndpoint  Config:63  Configured endpoint "get /v1/cards/{card_token}" has no matching operation in the document; the method is skipped.

Severity and failing the build

There are three severities. Five rules default to error: Config/ParseError, Config/InvalidIntegrationBranch, Document/ReferenceError, Pagination/UnknownScheme, and Target/InvalidGeneratedCode. The first four report input the generator cannot carry out as written: a configuration that does not parse, an integration branch it cannot use, a reference it cannot resolve, a pagination scheme that does not exist. Target/InvalidGeneratedCode is error for a different reason: the SDK it reports already fails to compile, so shipping it is never a passing outcome. Everything else, including every condition that used to pass silently, starts at warn or info, so the analysis never turns a healthy build red on its own.

Which severities fail the build is set in the diagnostics block of your SDK configuration:

{
  "diagnostics": {
    "failOn": "error",
    "maxWarnings": 20,
    "rules": {
      "Endpoint/NotConfigured": "warn",
      "Schema/EnumHasOneMember": "off"
    }
  }
}

• failOn is the lowest severity that fails the build, and defaults to error. Set it to warn to hold the build to a stricter standard, or to off to report without ever failing.
• maxWarnings and maxErrors are checked independently of failOn, so you can let warnings through while capping how many of them accumulate. Exceeding either one fails the build.
• rules re-grades a rule by code. off disables it entirely, so it neither reports nor counts toward failing the build.

Overrides and suppressions are applied before these thresholds are checked, so a rule you graded down or a finding you suppressed cannot fail a build.

Provenance: whose file holds the fix

Each rule declares which document a finding is a critique of, which is what separates "fix your API description" from "fix your configuration":

The configuration Scalar generates for you is meant to report no config findings on its first build: the configuration generator applies the same rules the analyzer checks. Findings with document provenance legitimately survive a first build, because no configuration can invent what the description does not say.

Suppressing a finding

Sometimes a finding is correct and the situation is still intentional — an endpoint that is deliberately not in the SDK, an example that shows a failing request on purpose. Use diagnostics.ignored to record that intent, keyed by rule code:

{
  "diagnostics": {
    "ignored": {
      "Schema/EnumHasOneMember": true,
      "Endpoint/NotConfigured": "get /internal/*",
      "Model/Recommended": [
        { "location": "ApiError", "reason": "expanded inline on purpose" },
        { "target": "go", "reason": "not shipped for Go yet" }
      ]
    }
  }
}

• true suppresses the rule everywhere. Prefer a narrower form when you can, so a new occurrence still gets reported.
• A string matches the finding's suppression key, exactly or with * as a wildcard.
• An entry list mixes location matches (the same key grammar) with target matches, and each entry can carry a reason that stays with the suppression.

Suppressing is not the same as disabling. A suppressed finding is still produced and still recorded — it just does not count toward failing the build — whereas "rules": { "...": "off" } stops the rule from running at all.

Every rule's suppression key is listed alongside it below.

What we check

Configuration and endpoints

Document and references

Schemas and models

Responses, pagination, and security

For what a pagination scheme declares and how methods bind to one, see Pagination.

README examples

The generated README is code that has to compile, so its configured examples are checked against the methods actually generated.

Runtime support and generator health

gRPC

These fire only when the SDK is generated from a proto file.

AsyncAPI

An AsyncAPI build reports its own rule families — unsupported protocols and schema formats, unconfigured channels, and specification features that are read but not yet generated for. The rules that only fire on an AsyncAPI document are listed on the AsyncAPI page, and they are graded and suppressed exactly like the rules above.

Rules that read an OpenAPI shape do not run on an AsyncAPI document, so an AsyncAPI build is quieter than an OpenAPI one about the same underlying problem.

Next steps

• Configuration — the diagnostics block reference
• Managing your SDK — where build output and logs live
• AsyncAPI — the AsyncAPI rule family