Troubleshoot DID resolution

Find out why a hosted did:webvh identifier, its latest version, or its agent name does not resolve from your WebVH Hosting appliance, and fix it.

Find out why a hosted DID, its latest version, or its agent name does not resolve from your WebVH Hosting appliance.

Resolving a hosted DID means fetching its did.jsonl log from a URL built from the DID itself. Most failures come from requesting the wrong URL, from caching, or from a DID that is no longer on the appliance. For where a DID resolves and why, see DID lifecycle.

Use this guide when:

  • A resolver or curl returns 404 for a hosted DID.
  • A DID still resolves to an old version after an update.
  • An agent name such as /@alice does not redirect.

Prerequisites

  • PNM connected to the VTA that manages the DID.
  • The DID, for example did:webvh:Q1abc…:did.example.com:my-service.

Step 1. Build the DID’s URL

A did:webvh DID has the form did:webvh:<SCID>:<domain>:<path>. Its log is at:

  • DID with a path: https://<domain>/<path>/did.jsonl. Colons inside the path become slashes, so …:did.example.com:org:my-service resolves at https://did.example.com/org/my-service/did.jsonl.
  • DID with no path: https://<domain>/.well-known/did.jsonl.

On the Affinidi-hosted appliance, <domain> is the host of the appliance’s WebVH URL in Affinidi Portal.

Step 2. Request the log

curl -sI "https://did.example.com/my-service/did.jsonl"
ResponseMeaning
200 with content-type: application/jsonl+jsonThe appliance serves the DID. If a resolver still fails, the problem is on the resolver’s side, such as a stale cache.
404The appliance has no DID at this URL. See Match the symptom.

A successful response carries cache-control: public, max-age=300, so resolvers and proxies can reuse it for up to 5 minutes.

Step 3. Match the symptom

SymptomLikely causeFix
404 for a DID you just createdThe new DID is still syncing to the appliance’s edge.Wait a few seconds and retry.
404, and the URL’s host differs from the DID’s domainThe request went to a different host.Request the domain embedded in the DID. The appliance serves each DID only on its own domain.
404, and the URL’s path differs from the DID’s pathThe path is misspelled, or its colons were not converted to slashes.Rebuild the URL as in Step 1.
404, and pnm did-mgmt dids get <did> shows no serverThe DID is serverless, so no hosting server serves it.Create the DID on your appliance with --server, or register the serverless DID with the appliance.
404 for a DID that pnm did-mgmt dids list no longer showsThe DID was deleted.Deletion is permanent. Create a new DID if you need one.
An old version is returned after an updateThe previous response is still cached, for up to 5 minutes.Wait and retry. Run pnm did-mgmt dids get-log <did> to see the latest version your VTA published.
A deleted DID still resolves after 5 minutesThe deletion did not reach the appliance, so the DID was left behind.Run pnm did-mgmt dids reconcile --server my-webvh as an unrestricted VTA admin to confirm, then contact Affinidi support to remove it.
/@alice returns 404The name is parked, released, or not yet bound.Run pnm did-mgmt agent-names list --did <did> to check the name’s state, and bind or enable it. See Give a DID a human-readable name.
/<path>/did.json returns 404The appliance serves the did.jsonl log only.Resolve the DID with a did:webvh resolver, which reads did.jsonl.

Confirm

Test 1: request for the DID’s log returns 200

curl -sI "https://did.example.com/my-service/did.jsonl"

Expected output: HTTP/2 200 with content-type: application/jsonl+json.

Test 2: latest log entry matches your VTA’s latest version

curl -s "https://did.example.com/my-service/did.jsonl" | tail -n 1 | jq '.versionId'
pnm did-mgmt dids get-log did:webvh:Q1abc…:did.example.com:my-service | tail -n 1 | jq '.versionId'

Expected output: the same versionId from both commands, once any cached response has expired.

Next steps