Failure modes and debugging

Most OLPN failures fall into a small number of categories. The reference resolver's verification trace surfaces each one with a specific message. This page maps the common failure modes to their causes and fixes.

Entity document failures

"No olpn.json found at {domain}"

The resolver tried both /olpn.json and the HTML <script id="olpn-hub"> fallback, and neither returned a parseable document.

• Confirm https://{domain}/olpn.json returns HTTP 200 and valid JSON from an external fetch. Don't rely on a private preview URL.
• Confirm content-type is application/json (or text/json). Hosts that serve as application/octet-stream will produce warnings and, depending on the resolver, parse failures.
• If using the HTML embed, confirm the script tag is served in the page body, the id is exactly olpn-hub, and the type is exactly application/json.

"Document missing network_id"

The document parsed but the required network_id field is empty or absent. Add it. The value must be of the form §:entity:{domain}.

Property failures

"Property {id}: no olpn-property.json at {domain}"

The property's domain doesn't serve an olpn-property.json. Either:

• Add one. See Publish an ownership record.
• The domain isn't yours and never will be. Remove the property entry from your olpn.json.

"Property {id}: entity not in ownership[]"

The document exists but doesn't name you. Add your network_id to the ownership[] array on the property side. If the property is owned by someone else, this is expected and the claim should be removed from your entity document.

Credential failures

"Credential {id}: invalid format"

Credential IDs must be @username@domain[/path] with a leading @ and exactly one more @ as a separator. Common mistakes:

• Missing the leading @ ([email protected] instead of @[email protected]).
• Using a URL-like form ([email protected]/attorneys/?active). Query strings and fragments aren't permitted.
• Multiple @ in the username (@jane@[email protected]). Everything after the first @ is treated as domain+path, so the parser will try to fetch https://[email protected]/jane/olpn-credential.json, which won't work.

"Credential {id}: issuer document not found"

The resolver fetched https://{domain}/{username}/olpn-credential.json and got a 4xx or 5xx. The issuer hasn't published this credential yet, or the username path doesn't match. If you generated the ID from a firm bio URL, confirm that the firm's credential publishing endpoint uses the same username path.

"Credential {id}: olpn_entity_id mismatch"

The issuer's credential document exists but names a different entity. This is the classic case of a firm that hasn't updated its records after an attorney moved domains, or a bar association that issued to a different network ID.

Reach out to the issuer and ask them to update the back-link. The mismatch message in the trace usually includes the network ID the issuer actually set, so you can show them exactly what to change.

Timeouts

The resolver times out fetches after 10 seconds. Slow origins, rate-limited endpoints, and connectivity issues all look like "not found" to the user. If you control the issuing domain, check your logs for blocked or throttled requests from the resolver's IP range.

When in doubt, read the trace

Every reference-resolver results page has a "Show Details" section with a timestamped step-by-step log of what the resolver did: URLs fetched, response status, parse results, back-link comparisons. It is the fastest way to find the specific line that failed.