Troubleshooting
Find the symptom, then apply the fix. Each cookbook lists only the problems that are specific to its steps; everything else is collected here.
When a wallet is involved, collect its log right after the failure: in the EU Reference Implementation open Settings → Retrieve Logs, in Paradym Wallet open Settings → Export Logs. The wallet compatibility record has details for other wallets. On the EUDIPLO side, open the session under Sessions → All Sessions in the Web Client: a failed session shows why it failed, its failure code where one is recorded, and the wallet's own description when the wallet reported the failure. GET /api/session/{id} returns the same as described in Session Outcome. Remove tokens, keys and personal data before you share logs.
Install and connect
| Symptom | Cause | Fix |
|---|---|---|
eudiplo: command not found after the installer ran | ~/.local/bin is not on your PATH | Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new shell. |
| Installer stops with "npm is required" | No standalone build for this platform (for example an Intel Mac); the installer falls back to npm | Install Node.js 22.12 or later, then rerun the installer, or use npx @eudiplo/cli. |
Docker or Podman was not found | No container runtime on the PATH, or it is not running | Install and start Docker or Podman; set EUDIPLO_CONTAINER_RUNTIME=docker or podman to choose one. |
| "port is already allocated" when starting | Another EUDIPLO stack, often eudiplo demo, uses port 3000 or 4200 | Stop it, for example eudiplo down --instance local for the demo, then run eudiplo up --instance <name>. |
Unknown instance or a command acts on the wrong stack | The CLI default instance is a different one | Run eudiplo instance list and pass --instance <name>, or make it the default with eudiplo instance use <name>. |
An edit to .eudiplo.env has no effect | The running container still has the old environment | Run eudiplo up --instance <name>; Compose recreates changed containers. eudiplo restart does not reload the environment. |
| Backend exits right after start | Invalid environment, for example a malformed CORS_ORIGINS or a missing secret | Read eudiplo logs --instance <name> --service eudiplo --tail 100; the first error names the variable. |
localhost health works, the phone cannot reach the backend | The tunnel stopped, forwards to another port, or shows a confirmation page | Restart the tunnel to port 3000. Open https://<public-host>/health in the phone's browser; it must show the JSON directly. |
Login
| Symptom | Cause | Fix |
|---|---|---|
| Web Client login hangs or reports a connection error | EUDIPLO Instance points to an address the browser cannot reach, such as http://eudiplo:3000, which older Compose files prefill | Enter the backend address as your browser reaches it, for example http://localhost:3000. A trailing slash is removed automatically. |
Web Client login hangs or reports a connection error, although <EUDIPLO Instance>/health opens in the browser | The token request fails. It goes to the token endpoint of the discovery document, PUBLIC_URL/api/oauth2/token (with OIDC set, the provider's), not to the EUDIPLO Instance: for example a stopped tunnel, a WAF or proxy that blocks the browser's address, or a CORS error | Open PUBLIC_URL/health (with OIDC, the provider's address) in the same browser and start the tunnel or proxy, or correct PUBLIC_URL and run eudiplo up. The browser's network tab shows the failing request (web client addresses). |
| Login page shows "Resuming the session of …" instead of the form | The open tab kept its session and keeps renewing its token, but the token request gets no answer (backend stopped, restarting or removed), fails with an error other than 400 or 401, or is blocked for CORS | Open <backend>/health in the browser, at PUBLIC_URL if it differs from the EUDIPLO Instance (the token endpoint is there, see the row above). If it does not answer, start the backend; the page then signs in by itself and returns to the page you were on. For a CORS error in the browser console, see the CORS row below. To sign in elsewhere, choose Sign out and use other credentials; you need the client secret again. |
| "Your session expires in … minutes", "Your session has expired" or, on the login page, "The session of … expired" some time after a page reload or in a newly opened tab | The Web Client keeps the client secret in memory only, in the tab you logged in with. Only that tab renews the token; a reloaded tab, or one opened later, takes over each token it renews. Once no open tab holds the secret, for example because that tab was closed or reloaded too, the session lasts until the token expires (token lifetime) | Keep the tab you logged in with open, or log in again. The login form keeps the client ID and instance, so enter the client secret; signing in as the same client returns to the page you were on. |
| Login rejected with valid-looking credentials | Wrong client ID or secret | eudiplo demo uses root / root; eudiplo init generates the secret, see AUTH_CLIENT_SECRET in .eudiplo.env. Tenant clients: rotate the secret under Administration → API Clients. |
The token endpoint always answers 401 | The instance uses an external OIDC provider such as Keycloak | Get tokens from the identity provider. With Keycloak, the login page also has an SSO tab; with another provider (OIDC_PROVIDER=generic), only once OIDC_UI_CLIENT_ID is set. See Keycloak SSO and another provider. |
| "Your API client no longer has access" | The client you signed in with was deleted, or its tenant was, or its secret changed | Sign in with another client, or with the new secret. To give a service access again, create its client again or give it the new secret (revoke access). |
| "Your API client no longer has the role …" or "Your API client lacks a role this page needs" (with single sign-on: "Your account …") | Someone removed a role from the client you signed in with, or from your account in the identity provider | The Web Client hides the pages of that role. On a page that needs it, copy unsaved changes and choose Leave page. Ask for the role again if you need it. |
| Signed in, but menu sections are missing | The client lacks the roles for them | Have a client that holds the roles, or tenant:admin, add them; without tenant:admin, a client cannot add roles to itself (granting roles). The Web Client builds its menu from the roles the backend reports for the signed-in caller (GET /api/auth/me), once per token, so the new roles appear with the next token; sign in again to see them at once. |
| "Could not load your roles: …", and menu sections are missing, the dashboard shows nothing for your roles, or the page does not open | The Web Client could not get the roles of the signed-in caller from GET /api/auth/me: the backend is unreachable or older than the Web Client, or a proxy blocks the path | Run the backend and the Web Client from the same release and let /api/auth/me through the proxy, then choose Retry in the notice; it opens the page you asked for. |
API calls return 401 with "The client of this token does not exist" or "This token was issued for the client's earlier credentials" | The client was deleted, its tenant was, or it got a new secret (also by a configuration import) since the token was issued | Request a new token with the current secret. To give a service access again, create its client again or give it the new secret (revoke access). |
API calls return 401 with "Not an access token: …" | In OIDC mode (Keycloak or another provider), the caller sent the provider's ID token, or another kind of token, instead of the access token | Send the access token the provider issued with it (with Keycloak, access_token of the token response, not id_token; Keycloak, another provider). |
API calls return 403 | The client lacks the role of the endpoint, for example issuance:offer (with Keycloak: the token) | Give the client the documented role. Never give a tenant client tenants:manage. |
API calls return 403 "This endpoint requires a tenant context" | The token names no tenant, or one that does not exist: the root client's token, or an identity provider's token without the tenant claim | Use a client of the tenant. With an identity provider, put the tenant ID into the token (Keycloak, another provider). |
403 "Cannot grant …" or "Cannot manage …" | The roles involved go beyond the caller's own | Use a client that holds those roles or tenant:admin (granting roles). |
| Signed in, but actions fail with "… the backend could not be reached" | The backend stopped or is restarting, the network dropped, or the browser blocked the request for CORS (next row) | Open <backend>/health in the browser. If it does not answer, read eudiplo logs --instance <name> --service eudiplo --tail 100, then retry the action. |
Browser console shows a CORS error for /api/... | CORS_ORIGINS does not include the page's origin | Add the exact origin (scheme://host[:port], no trailing slash) and run eudiplo up. |
Wallet connection
| Symptom | Cause | Fix |
|---|---|---|
| Wallet cannot open the offer or request | PUBLIC_URL is not reachable from the phone, or it changed after the offer was created | Check the health endpoint on the phone. Correct PUBLIC_URL, run eudiplo up, and create a new offer. |
Offers or metadata contain localhost | PUBLIC_URL is still the default | Set PUBLIC_URL to the public HTTPS address and run eudiplo up. |
| Wallet rejects the issuer or verifier certificate | The wallet does not accept self-signed certificates, or needs registrar certificates | Follow Wallet and registrar requirements. Do not weaken verification to get around it. |
Wallet reports invalid_dpop_proof or a DPoP error | The wallet does not send a valid DPoP proof, or the proof's key differs from the one bound earlier | Use a wallet with DPoP support, or relax the DPoP setting of the issuer. See Authorization servers. |
Wallet reports a PKCE or invalid_request error at authorization | Since 9.0, authorization codes require PKCE with S256 | Use a wallet that sends an S256 code challenge. |
Issuance
| Symptom | Cause | Fix |
|---|---|---|
Session stays active | The wallet never fetched the offer | See Wallet connection. |
Session stays fetched | The credential was delivered, but the wallet sent no notification | Nothing to fix; only a credential_accepted notification moves the session to completed. |
POST /api/issuer/offer returns 409 for the claims | The claims do not match the claim fields of the credential configuration | Send every mandatory claim with the configured type. See Claims. |
Wallet gets invalid_grant or "The session has expired" | The offer outlived its lifetime | Create a new offer; adjust offerLifetimeSeconds if needed. |
| Wallet asks for a key attestation | The credential's supported proof types require one | Add proof type JWT, or use a wallet with key attestation. |
| "No key chain found with usage type ..." | The tenant has no key chain for that purpose | Create one under Cryptographic Assets → Keys. |
Token request answers 500 "The tenant's authorization server key chain is not available." | token.signingKeyId of the authorization server or the authorizationServer entry of key-chain-defaults.json names a key chain that does not exist or is not an authorization server key chain, as values stored before 10.0 do; or nothing names one and a key chain with ID authorization-server of another usage type blocks the one EUDIPLO creates. The backend log names the cause | Choose an Authorization Server key, or remove the value to use the tenant's authorization server key chain; in the second case, create an Authorization Server key. See Authorization server key chain. |
| Attribute provider or webhook is never called | The URL is HTTP or private, which the outbound URL policy blocks by default | Use a public HTTPS URL. For local development only, set OUTBOUND_URL_ALLOW_HTTP=true and OUTBOUND_URL_ALLOW_PRIVATE_NETWORK=true. |
| "Failed to fetch authorization server metadata" or "Failed to fetch upstream OIDC configuration" | The external authorization server or the chained server's upstream provider is on HTTP or a private address, which the outbound URL policy blocks by default; the log names the rejected URL | Use a public HTTPS URL. For local development only, set OUTBOUND_URL_ALLOW_HTTP=true and OUTBOUND_URL_ALLOW_PRIVATE_NETWORK=true. |
| The credential in the wallet shows old values | A wallet keeps the claims it was issued with | Issue a new credential after changing configuration or claims. |
Presentation
| Symptom | Cause | Fix |
|---|---|---|
| Wallet finds no matching credential | Format, VCT or claim paths differ from the issued credential, or trusted_authorities excludes its issuer | Compare the DCQL query with the credential type. See DCQL. |
Saving a presentation configuration fails with Credential queries without trusted_authorities | A credential query has no trust list or federation trust anchor | Add one under Issuer trust. See DCQL. |
| Wallet rejects the verifier | The access certificate is missing, inactive or not trusted by the wallet | Select an active access key chain in the presentation configuration; see Wallet and registrar requirements. |
| Request rejected for overasking | The registration certificate does not cover every requested credential and claim | Update the registration certificate to match the DCQL query. An imported jwt that does not match is already refused when the configuration is saved. See Registration certificates. |
| Wallet gets "The session has expired" | The request outlived its lifetime (default 300 seconds) | Generate a new request and approve it sooner, or raise the lifetime. |
Session failed with access_denied | The user declined in the wallet | Expected; offer a new request. |
Session failed with trust_chain_not_trusted or no_trust_chain_to_root | The issuer is not on the trust lists of the credential query, or its certificate is listed under another service type than PID, Pub-EAA or EAA issuance, or, in a Trusted List, than a granted qualified QEAA service (Svctype/EAA/Q with status granted; a withdrawn service no longer counts). For an mDOC, also a status list not signed under the signer its issuer's entry requires. An issuer only on a list discarded as outdated, or on a Trusted List that a list of trusted lists points to and that could not be loaded, counts as not listed (Discarded outdated trust list(s) ... or Discarded outdated or unavailable trust list(s) ... in the backend log names the list), and so does a QTSP whose Trusted List is not followed, for example because schemeTerritories names another territory, and so does one whose service is ignored for its ServiceStatus or a missing type (Trust list ... left out ... in the backend log, see Service status and type). For no_trust_chain_to_root, also an SD-JWT VC whose certificate path is past the size limits (the log says Certificate path not found within 64 signature checks or ... is longer than 16 certificates) | Add the issuer to the trust list with the right service type, or accept that the credential is rejected. For the size limits, ask the list's publisher to list each CA once, with its Subject Key Identifier. See Trust lists, Size limits and Accept only trusted issuers. |
Session failed with "Status List JWT verification failed" | The SD-JWT VC's status list does not verify, or is not signed under the signer its issuer's entry requires, for example under a revocation certificate of another service type, or its x5c holds more than 10 certificates (the server log says x5c holds ... certificates), or its certificate path is past the size limits (the server log says Certificate path ...) | Sign status lists under the revocation certificate that belongs to the issuer's issuance service, with only the signing certificate and its intermediates in x5c. For the size limits, ask the list's publisher to list each CA once, with its Subject Key Identifier. See Trust lists and Size limits. |
Session failed with trust_list_unavailable | A trust list could not be loaded (also when the outbound URL policy blocks its HTTP or private URL), lacks verification material, the lists of the query hold more than 1,000 certificates together (the log says brings the certificates of its source to ...), or every list of the query is outdated (no valid NextUpdate or one that has passed, or no valid LoTESequenceNumber or TSLSequenceNumber, or a lower one than a list accepted before). For a Trusted List (format: "trusted-list"): it is not signed by one of its signingCertificates (the log says ... is not a Trusted List signed by one of its signing certificates), its signature uses transforms or references outside ETSI TS 119 612 (... is refused before its signature is checked: ...), none of the lists its list of trusted lists points to could be loaded and no other list of the query's etsi_tl entry is left, or it points to more than 64 lists | Check the list URL, the backend log and its verifierX509Der, verifierKey or signingCertificates; for a list of trusted lists, name the territories you need in schemeTerritories (Trusted Lists for QEAAs). Discarded outdated trust list(s) ... in the log names outdated lists: ask its publisher for a current one, or for a managed list look for Failed to renew trust list. If the log says LoTESequenceNumber ... is lower than ... accepted before, see Older versions of a list. If it says brings the certificates of its source to ..., reference fewer lists together or ask the publisher for a smaller list (Size limits). See Trust lists. |
Session failed with "Status is not valid" | The credential is revoked or suspended | Expected after revocation. See Revocable credentials. |
| No webhook arrives | The endpoint is unreachable or blocked by the outbound URL policy, or it redirects to a URL the policy blocks (the log shows redirectTarget); webhooks are not retried | Check the backend log, then read the result with GET /api/session/{id}. See Receive results. |
Session shows active after its expiry time | The expired status is written by a periodic cleanup job | Compare expiresAt with the current time instead of waiting for expired. |