Troubleshooting

Start from the symptom: a module answers 404, a release never becomes ready, a job waits or stops, access is refused, or events stop arriving.

  • Availability: Planned
  • Evidence: Read from source
  • How-to guide

How to use this page

Find your symptom, run the safe checks, then follow the recovery. Every check here is a read: no GET starts work, so you cannot make things worse by looking. Nothing on this page asks you to delete an application, republish a package or retry blindly after a timeout.

Keep the identifiers at hand: the application, the release and its number, the job, and the exact URL with its query.

A module answers 404

Code Cause Recovery
OUTPUT_NOT_AVAILABLE The CDN knows the module and does not hold this output. The option set was not prepared, or the asset is not declared. Compare your query with the canonical query your release was prepared with. Prepare a release that includes the output. Reloading will not help.
MODULE_NOT_FOUND The subpath is not a public module of that package version Check the package's public modules. An internal file is not addressable.
VERSION_MISMATCH The package is known at another version Read the resolution of your release for the pinned version
PACKAGE_NOT_FOUND The package is not part of anything the service holds Check the name and the registry prefix

If the same URL works on your Dev Server and not on the CDN, that is expected for a missing output: the Dev Server compiles on request and the CDN never does. See Same URL, local and CDN.

A request answers 400

OPTION_INVALID means the query is wrong: a misspelled value, a repeated or unknown option, a missing target or format, or any query on an asset. OPTION_UNSUPPORTED means the query is right and this service never produces that output. On a Dev Server the usual cause is omitting env=development&min=false. See Request options.

A release never becomes ready

Read the release, then its job and its inventory.

What you find Meaning Recovery
Job failed with DYNAMIC_IMPORT_UNKNOWN; inventory counts.unknown above zero A dynamic import has a target that static tracing cannot determine Register again with a declared member that lists, for the importing public module, the public modules it may load. If the package is yours, you can put the same declaration in its module manifest and publish a new version instead.
BUILD_FAILED with diagnostics A module does not compile Fix the source. Build errors are reported on every plan.
CLOSURE_INCOMPLETE A required output is missing, failed or not retrievable Find the items in state failed or limit_exceeded in the inventory
INTEGRITY_MISMATCH A downloaded archive does not match the pinned integrity Do not override it. Check the registry and register again.
RESOLUTION_FAILED The graph could not be pinned Read the message: a missing version, conflicting ranges or an unsatisfied peer. Adjust selections or overrides.
UPSTREAM_UNAVAILABLE A registry did not answer for an input that was not cached Try the registration or preparation again later, with the same Idempotency-Key if the first request may have been accepted

In every case the active release is unchanged, and your site keeps serving it.

A job waits for a long time

queued and waiting_turn are normal on the free plan: jobs share one queue with no SLA, and each application works in short turns. queue.position and turns on the job tell you where it stands. Closing the tab changes nothing; the job does not depend on it.

A job ends in limit_exceeded

One module could not finish inside the execution budget of the plan. It is not retried automatically, because it would fail the same way. Either reduce what that public module pulls in, or ask for premium execution through the waitlist.

A request is refused

Answer Meaning
401 UNAUTHENTICATED The management request has no valid session
403 FORBIDDEN You can see the resource, and your role lacks the capability. See the capability table.
404 NOT_FOUND on something you expected You may not be allowed to know it exists. Check that you are in the right organization.
403 ENTITLEMENT_REQUIRED The plan does not include the capability named in details.entitlement
402 CREDIT_INSUFFICIENT, 503 BUDGET_EXHAUSTED Admission refused the work. Nothing was started and nothing was charged.
409 CONFLICT_VERSION Someone changed the resource first. Read it again; do not resend with the new number without looking.
401 ACCESS_REQUIRED, 403 ACCESS_DENIED on delivery The application is private. 401 means no access cookie, or a grant that ran out: exchange again. 403 means the grant was revoked or belongs to another application. See Private access.
501 NOT_IMPLEMENTED The operation is in the contract and this service instance does not mount its area; details.operation names it. Retrying does not help.

After a timeout, you do not know whether it worked

Send the same request with the same Idempotency-Key. If the first one was accepted you get its original result; if it was not, this one is accepted. Never generate a new key for a retry: that is how duplicate registrations and preparations are created.

Events stopped arriving

Notifications can be lost. Replay from your cursor; on CURSOR_EXPIRED or resync.required load a snapshot. If you received access.revoked, your access to that channel ended. See Reconnect and replay and Revocation.

A custom domain does not verify

DOMAIN_UNVERIFIED lists the TXT values the check observed. Compare them with verification.value, mind the exact record name, and allow for DNS propagation before trying again. The domain serves nothing until it is verified.

What to include when you ask for help

The exact URL or operation, the status and code, the application, release and job identifiers, and the time. Never include tokens. Job logs are sanitized and safe to share inside your organization.