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. Common causes are requesting the wrong URL, caching, or 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 a log for the DID at this URL. If a resolver still fails, check the resolver next, starting with 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 has not finished publishing.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.Contact Affinidi support with the DID 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.

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