Skip to main content

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​

SymptomCauseFix
eudiplo: command not found after the installer ran~/.local/bin is not on your PATHAdd 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 npmInstall Node.js 22.12 or later, then rerun the installer, or use npx @eudiplo/cli.
Docker or Podman was not foundNo container runtime on the PATH, or it is not runningInstall and start Docker or Podman; set EUDIPLO_CONTAINER_RUNTIME=docker or podman to choose one.
"port is already allocated" when startingAnother EUDIPLO stack, often eudiplo demo, uses port 3000 or 4200Stop 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 stackThe CLI default instance is a different oneRun eudiplo instance list and pass --instance <name>, or make it the default with eudiplo instance use <name>.
An edit to .eudiplo.env has no effectThe running container still has the old environmentRun eudiplo up --instance <name>; Compose recreates changed containers. eudiplo restart does not reload the environment.
Backend exits right after startInvalid environment, for example a malformed CORS_ORIGINS or a missing secretRead eudiplo logs --instance <name> --service eudiplo --tail 100; the first error names the variable.
localhost health works, the phone cannot reach the backendThe tunnel stopped, forwards to another port, or shows a confirmation pageRestart the tunnel to port 3000. Open https://<public-host>/health in the phone's browser; it must show the JSON directly.

Login​

SymptomCauseFix
Web Client login hangs or reports a connection errorEUDIPLO Instance points to an address the browser cannot reach, such as http://eudiplo:3000, which older Compose files prefillEnter 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 browserThe 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 errorOpen 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 formThe 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 CORSOpen <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 tabThe 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 credentialsWrong client ID or secreteudiplo 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 401The instance uses an external OIDC provider such as KeycloakGet 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 changedSign 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 providerThe 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 missingThe client lacks the roles for themHave 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 openThe 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 pathRun 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 issuedRequest 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 tokenSend 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 403The 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 claimUse 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 ownUse 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 originAdd the exact origin (scheme://host[:port], no trailing slash) and run eudiplo up.

Wallet connection​

SymptomCauseFix
Wallet cannot open the offer or requestPUBLIC_URL is not reachable from the phone, or it changed after the offer was createdCheck the health endpoint on the phone. Correct PUBLIC_URL, run eudiplo up, and create a new offer.
Offers or metadata contain localhostPUBLIC_URL is still the defaultSet PUBLIC_URL to the public HTTPS address and run eudiplo up.
Wallet rejects the issuer or verifier certificateThe wallet does not accept self-signed certificates, or needs registrar certificatesFollow Wallet and registrar requirements. Do not weaken verification to get around it.
Wallet reports invalid_dpop_proof or a DPoP errorThe wallet does not send a valid DPoP proof, or the proof's key differs from the one bound earlierUse 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 authorizationSince 9.0, authorization codes require PKCE with S256Use a wallet that sends an S256 code challenge.

Issuance​

SymptomCauseFix
Session stays activeThe wallet never fetched the offerSee Wallet connection.
Session stays fetchedThe credential was delivered, but the wallet sent no notificationNothing to fix; only a credential_accepted notification moves the session to completed.
POST /api/issuer/offer returns 409 for the claimsThe claims do not match the claim fields of the credential configurationSend every mandatory claim with the configured type. See Claims.
Wallet gets invalid_grant or "The session has expired"The offer outlived its lifetimeCreate a new offer; adjust offerLifetimeSeconds if needed.
Wallet asks for a key attestationThe credential's supported proof types require oneAdd 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 purposeCreate 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 causeChoose 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 calledThe URL is HTTP or private, which the outbound URL policy blocks by defaultUse 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 URLUse 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 valuesA wallet keeps the claims it was issued withIssue a new credential after changing configuration or claims.

Presentation​

SymptomCauseFix
Wallet finds no matching credentialFormat, VCT or claim paths differ from the issued credential, or trusted_authorities excludes its issuerCompare the DCQL query with the credential type. See DCQL.
Saving a presentation configuration fails with Credential queries without trusted_authoritiesA credential query has no trust list or federation trust anchorAdd one under Issuer trust. See DCQL.
Wallet rejects the verifierThe access certificate is missing, inactive or not trusted by the walletSelect an active access key chain in the presentation configuration; see Wallet and registrar requirements.
Request rejected for overaskingThe registration certificate does not cover every requested credential and claimUpdate 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_deniedThe user declined in the walletExpected; offer a new request.
Session failed with trust_chain_not_trusted or no_trust_chain_to_rootThe 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_unavailableA 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 listsCheck 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 suspendedExpected after revocation. See Revocable credentials.
No webhook arrivesThe 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 retriedCheck the backend log, then read the result with GET /api/session/{id}. See Receive results.
Session shows active after its expiry timeThe expired status is written by a periodic cleanup jobCompare expiresAt with the current time instead of waiting for expired.