Skip to main content

Troubleshooting

Credential reception​

The wallet shows "Unsupported credential format"​

Symptom: when scanning a QR or opening an issuance deep link, the wallet shows an error indicating the format is not compatible.

Cause: the issuer is offering the credential in a format other than jwt_vc_json. The vc+sd-jwt and ldp_vc formats are not supported.

Solution: contact the issuer to confirm the offer uses the jwt_vc_json format. If the issuer is in the ISBE ecosystem, they can consult the OID4VCI/VP Reference to adjust the configuration.

The wallet shows "Incorrect transaction code"​

Symptom: when entering the tx_code PIN, the wallet rejects the code.

Common causes:

  • The code has expired. Transaction codes have a short validity period defined by the issuer.
  • The code was entered with an incorrect character.
  • The code was already used in a previous failed attempt and the issuer has invalidated it.

Solution: request a new code from the issuer and try again.

The wallet shows "Credential offer expired"​

Symptom: the QR or deep link is no longer valid.

Cause: the pre-authorized_code of the offer has a validity period (defined by the issuer) that has elapsed.

Solution: ask the issuer to generate a new credential offer.

The credential remains in "Pending" state indefinitely​

Symptom: after accepting an offer, the credential appears as pending and does not arrive.

Cause: the issuer uses deferred issuance and has not yet processed the request.

Solution: the wallet retries the query to the /deferred_credential endpoint periodically. If the credential does not arrive within a reasonable time, contact the issuer to verify the process status.

The wallet cannot scan the QR​

Symptom: the camera does not detect the QR code.

Common causes:

  • The camera permission has not been granted to the wallet.
  • Lighting is insufficient.
  • The QR is damaged or too small on screen.

Solution: go to the operating system settings and verify that the wallet has camera permission. Adjust the lighting or enlarge the QR on the issuer's screen.

Credential presentation​

The wallet finds no credential meeting the request​

Symptom: after scanning a verifier's QR, the wallet indicates you have no credential satisfying the criteria.

Common causes:

  • You do not have the requested credential type. The verifier is requesting a type of credential you have not yet received.
  • The credential you had has expired.
  • The verifier's DCQL query requires specific attributes that your credential does not include.

Solution: obtain the requested credential type from the corresponding issuer. If the credential has expired, request a renewal from the issuer.

The verifier rejects the presentation​

Symptom: the wallet indicates the presentation was sent, but the verifier returns a validation error.

Common causes:

  • The credential has been revoked by the issuer (the wallet does not check revocation, but the verifier may do so).
  • The issuer's DID is not accredited in the ISBE TIR for the presented credential type.
  • The nonce in the VP does not match the one sent by the verifier (possible cache or timing issue).

Solution: contact the verifier to obtain the specific error code. If the credential was revoked, request a new one from the issuer.

The wallet shows "Response method not supported"​

Symptom: when trying to respond to a verification request, the wallet shows a method error.

Cause: the verifier is using a response_mode other than direct_post. The wallet only supports direct_post.

Solution: the verifier must configure response_mode: direct_post in their authorization_request.

Identity and account​

Biometric authentication does not work​

Symptom: Face ID, Touch ID, or fingerprint does not unlock the wallet.

Common causes:

  • New fingerprints or faces were added to the operating system after enabling biometrics in the wallet. For security, the wallet requires PIN re-authentication when the device's biometric data changes.
  • The operating system biometrics are disabled.

Solution: use your PIN to unlock the wallet. Then go to Settings → Security to reconfigure biometric authentication.

The wallet shows "DID not resolvable" when receiving a credential​

Symptom: the wallet cannot verify the issuer's signature because it cannot resolve their DID.

Common causes:

  • The device has no internet connectivity.
  • The issuer's DID is not registered on the ISBE blockchain of the corresponding environment (production, pre-production, or development).

Solution: verify internet connectivity. If the problem persists, the issuer must check that their DID is correctly published in the ISBE TIR.

General issues​

The wallet crashes unexpectedly​

Solution: fully close the app and reopen it. If the problem persists, reinstall the wallet (credentials stored on the device will be lost). Report the problem to the ISBE team with the reproduction steps and the wallet and operating system version.

Where do I find the wallet version?​

On iOS: System Settings → ISBE Wallet → Version.
On Android: System Settings → Apps → ISBE Wallet → App info.

You can also check the version inside the wallet at Settings → About.