Troubleshooting
This page lists the problems you're most likely to hit when building and publishing an SDK, with the exact messages you'll see and how to fix each one.
To see what happened to a build, open Builds in SDK Studio and expand it. Each language shows its own result, and a failed quality check links to its job log. The CLI shows the same, plus build health across runs.
Before you build
Run these first. They catch most problems in seconds, without using a build.
In the dashboard, that's the Spec Auditor and the live preview in SDK Studio. From the CLI, it's octri sdk validate, audit and preview.
Starting a build
Generation
Quality checks
A failed check doesn't remove the source. You can still download it, but read the job log before relying on that package.
| Check that failed | Usual cause | What to do |
|---|---|---|
| Generate | The spec can't be turned into code | See generation above |
| Format, Lint | Style warnings in generated or hook code | These don't block promotion if Compile and Package pass |
| Compile | Your hooks don't compile, or a name isn't legal in that language | Open the job log for the compiler's error. Hook code is the first place to look |
| Native tests | Generated tests fail, often from a hook changing behavior | Check the hook against the failing test |
| Contract tests | The SDK doesn't match your spec, often because a response example doesn't fit its schema | Fix the example or the schema |
| Package | The manifest is invalid, often the package name or version | Check the package name |
| Consumer install | A fresh project can't install it, often from a bad hook dependency | Check hookPackages |
Repositories and promotion
Publishing to a registry
When developers use the SDK
Still stuck
Give support the build ID, the language, and the first failing check. Find the ID in Builds, or with octri sdk builds.