Common Errors
Most early OAN failures are not mysterious. They usually come from incomplete metadata, domain mismatch, DID inconsistency, missing hash material, lifecycle delay, or endpoint configuration problems. The fastest way to debug is to identify which stage failed: registration input, Registrar validation, Root acceptance, publication, Discovery indexing, or client verification.
This page explains common error patterns in user language. Exact error names can vary by service version, but the underlying categories should stay stable.
When debugging, resist the urge to change everything at once. OAN has a staged pipeline, so the fastest repair is usually to identify the stage and fix that stage’s input. A Discovery no-result case is very different from a Root proof failure. A domain mismatch is very different from an endpoint timeout.
Domain Errors
Domain errors are common after the authorized-domain refactor because the field is now typed and enforced.
| Error pattern | Likely cause | What to do |
|---|---|---|
resource_domains_required |
The resource has no usable authorizedDomains. |
Choose a valid domain or let the Registrar compute one if supported. |
invalid_authorized_domains |
Domain IDs are malformed or not recognized. | Use canonical domain IDs and avoid free-form text. |
unauthorized_domains |
The Registrar or Discovery node does not cover the requested domain. | Use a node with matching scope or choose a covered domain. |
| Resource not visible in one Discovery node | The node may not cover that domain. | Check Discovery authorized-domain scope. |
Remember: capability tags cannot fix domain errors. A tag is not authorization.
A practical sign of a domain problem is asymmetric behavior across nodes. A resource may register through one Registrar but fail through another, or appear in one Discovery node but not another. That can be correct if node scopes differ. Check the node’s authorized domains before assuming search is broken.
Identity and DID Errors
Identity errors usually mean the DID, DID Document, or subject-control evidence does not line up.
Common causes include a DID Document id that differs from the submitted DID, missing verification methods, unsupported DID method syntax, stale proof material, or a resource type that does not match the metadata. For production resources, make sure the resource owner controls the relevant keys. Demo identity generated by a browser should not be confused with long-term organizational identity.
For teams, assign ownership of resource identity early. If a skill is published by an organization, the organization should understand where keys, DID Documents, version records, and update permissions live. Identity mistakes are harder to clean up after users have discovered and pinned a resource.
Hash and Package Errors
Root and clients use hashes to detect drift. If you see package hash, metadata hash, DID Document hash, or unsupported hash algorithm errors, assume the accepted material and submitted or fetched material do not match.
Typical fixes include regenerating hashes after editing metadata, ensuring package bytes are stable, checking line endings or serialization differences, using the expected hash algorithm, and avoiding last-minute changes to manifests or schemas after the package facts were prepared.
Hash errors often come from treating metadata as informal text. In OAN, accepted metadata and package references are evidence-bearing material. If you edit a README-like description that is part of the package snapshot, you may need a new hash and a new versioned submission.
Lifecycle Surprises
Not seeing a resource immediately after registration does not always mean failure. The resource may be:
- accepted by Registrar but not yet accepted by Root;
- accepted by Root but not yet published;
- published but not yet indexed by Discovery;
- indexed by one Discovery node but not another;
- active but filtered out by query constraints;
- superseded or revoked.
Check lifecycle status before resubmitting repeatedly. Repeated submissions can make debugging harder if each version has slightly different metadata.
If the UI or SDK exposes a request ID, package DID, version, or publication cursor, keep it while debugging. These identifiers let operators distinguish delayed processing from a fresh submission with different facts.
Discovery Query Errors
Discovery may return no results because the query is too vague, filters are too narrow, tags do not match, resource type is wrong, protocol is wrong, or semantic indexing has not caught up. Try removing optional filters, using a clearer task description, or searching by a known capability tag.
If one Discovery node returns results and another does not, compare domain scope and synchronization status. That difference may be correct behavior.
Semantic Discovery can introduce another subtle case: the resource is indexed but not ranked highly for the query. In that case, improving descriptions, examples, and tags in the next version can help. It is not a reason to bypass proof or stuff unrelated keywords into tags.
Endpoint and baseUrl Errors
When using SDKs or skills, configuration errors often look like service failures. Check whether baseUrl is correct, whether explicit endpoint overrides point to compatible services, and whether routes such as /registrar/status, /discovery/status, /root/status, and /cdn/status are reachable.
If you are using a third-party node, confirm that the operator exposes the expected route model. If you are using a temporary IP deployment, remember that later production domain migration may change the default official baseUrl.
For SDKs and skills, prefer configuration that can be changed without code edits. Environment variables, config files, or explicit options make it easier to switch from a temporary official IP to a final domain, or from official services to a trusted third-party deployment.
Verification Failures
A candidate can be found but still fail verification. This can happen when Discovery response signatures are invalid, Root proof is missing, package hashes do not match, lifecycle is not active, endpoint binding fails, or the node is no longer authorized.
Do not work around verification failures by manually calling the endpoint unless you intentionally leave OAN’s trust path. The safer fix is to identify the failed check and repair the underlying package, node state, or client configuration.
Verification failures are sometimes good news: they mean the system caught a mismatch before use. Treat them as a diagnostic signal. If a candidate cannot prove what it claims, the correct default is to stop, not to downgrade silently.