# 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](/products/affinidi-elements/webvh-hosting/concepts/did-lifecycle.md).

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

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

| Response | Meaning |
| 200 with content-type: application/jsonl+json | The appliance serves the DID. If a resolver still fails, the problem is on the resolver’s side, such as a stale cache. |
| 404 | The appliance has no DID at this URL. See [Match the symptom](#step-3-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

| Symptom | Likely cause | Fix |
| 404 for a DID you just created | The 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 domain | The 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 path | The 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 server | The 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 shows | The DID was deleted. | Deletion is permanent. Create a new DID if you need one. |
| An old version is returned after an update | The 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 minutes | The 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 404 | The 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](/products/affinidi-elements/webvh-hosting/webvh-management/agent-names.md). |
| /<path>/did.json returns 404 | The 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

```bash
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

```bash
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

- [Create and manage DIDs](/products/affinidi-elements/webvh-hosting/webvh-management/did-management.md): create, update, and delete hosted DIDs.

- [DID lifecycle](/products/affinidi-elements/webvh-hosting/concepts/did-lifecycle.md): how a DID is published, synced, and served.

## Related

- [Make a DID reachable over DIDComm](/products/affinidi-elements/webvh-hosting/webvh-management/didcomm-endpoint.md): add a DIDComm endpoint to a hosted DID.

- [Glossary](/products/affinidi-elements/webvh-hosting/get-started/glossary.md): terms used across these pages.