Unit troubleshooting — installation through events
Read error codes together with lifecycle phase, SDK release and instance identifier. HTTP listener, enrollment and active are different states. This order helps readers diagnose a problem; it does not require documentation authors to rerun tests.
Diagnosis order
| Stage | What to inspect | Meaning |
|---|---|---|
| Installation | Runtime, version, feed mapping, read permissions | Packages resolve; the instance is not necessarily linked |
| Host / parity | Listener, release document, complete handlers | Control Plane can read the correct contract |
| Identity / OIDC | Issuer, transport, audience and deployment settings | Tokens can be evaluated against the profiles |
| Enrollment | Control Plane, Dapr, link key, identity persistence | Instance is linked |
| Configuration / apply | Manifest fields, callback, assigned tenant | Unit can proceed to configured and active |
| Operation | Contract route, scope, tenant, required data | Handler can answer or refuse |
| Event | Declaration, publisher, consumer, publishedIn | Publication and consumption belong to the correct contract |
| Restart | Same persistent identity store | Instance restores identity rather than spending another link key |
Recognisable refusals
| Code / symptom | Meaning and next step |
|---|---|
Tenant.NotReady | Instance is not yet serving operations; inspect configuration and apply |
Operation.HandlerMissing | Declared operation has no handler |
Event.HandlerMissing | Required consumer missing in hosts reporting this code |
Profile.InsecureTransport | Issuer transport is inappropriate; use a profiles matching the release |
Unit.ListenFailed | TypeScript: listener could not bind the port |
HostError::IssuerRequired | Rust: enrollment lacks verify_tokens |
HostError::UndeclaredConfiguration | Rust: callback without declared fields |
HostError::NoRuntime | Rust: bind / serve outside tokio runtime |
Cat.NotFound | Example domain: requested cat does not exist |
NU1101 | NuGet: feed, mapping or package version does not match the project |
A host error code need not equal an exception variant name. Use the stable code returned by the selected SDK; do not transfer exception names between languages.
What to include in a problem report
Include versions, phase, refusal code, contract document and a synthetic-data reproduction. Anonymise tenant, user and private addresses. Do not include link keys, tokens, identity keys or configuration secrets.
Do not delete identity as the first repair step: the link key is single-use. Do not treat a parity response as proof of correct scopes or event consumption. Use your SDK tutorial and lifecycle; read RPC and Edge routing from the appropriate exposition.