How to troubleshoot in-person verification

This guide covers symptoms specific to in-person verification with the mDocs Verifier SDK. It assumes you know which events the flow emits, as described in Monitoring in-person verifications.

For the general method, which covers locating events by request ID, reading data.error, and what to send our support team, refer to How to monitor a flow.

In-person verification happens on the device, so your tenant only sees part of it. The app instance registers and renews its tokens with MATTR VII, and the SDK reports each verification after it happens. Everything in between takes place between the holder's wallet and your app. When an event you expect is missing, the SDK logs on the device are often the only other record of what happened.

Start every investigation from the applicationInstanceId of the device involved. It identifies a single installation of your app, and you can filter on it directly with applicationInstanceIds. You can list the instances registered against a verifier application using the Retrieve verifier application instances endpoint.

No verification events appear for your appCopy Anchor Link

What you will find: no CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS events for your verifier application, even though verifications are taking place.

Check the following, in order:

• The SDK version. Verification events are reported from the following mDocs Verifier SDK versions. Earlier versions do not report them.
  • iOS: 6.1.0
  • Android: 7.1.0
  • React Native: 10.1.0
• The tenant and verifier application. The SDK reports events to the tenant and verifier application set in the PlatformConfiguration you initialize it with. Confirm you are querying that tenant, and filtering on that verifier application's ID.
• The app instance registration. Query CREDENTIAL_PRESENTATION_VERIFIER_APPLICATION_INSTANCE_REGISTER_SUCCESS events for the verifier application. If there are none, the app never registered with your tenant. Refer to The app instance could not register.

The fix: update to a supported SDK version, and confirm the PlatformConfiguration in your app points to the tenant and verifier application you expect.

The app instance could not registerCopy Anchor Link

What you will find: CREDENTIAL_PRESENTATION_VERIFIER_APPLICATION_INSTANCE_REGISTER_START, then CREDENTIAL_PRESENTATION_VERIFIER_APPLICATION_INSTANCE_REGISTER_FAIL.

The SDK registers the app instance with your tenant the first time it is initialized on a device. If registration fails, the SDK cannot obtain a license and does not report verification events. The data.error on the FAIL event names the cause. Common causes are a verifier application configuration that does not match the app, such as a different bundle ID or team ID, or a device that could not provide the attestation the verifier application requires.

The fix: compare the app's details against the verifier application configuration. Refer to SDK Backend.

Events stopped arriving from one deviceCopy Anchor Link

What you will find: verification events for an applicationInstanceId up to a point in time, and none after it.

Look for CREDENTIAL_PRESENTATION_VERIFIER_APPLICATION_INSTANCE_ISSUE_TOKENS_FAIL for the instance. The SDK reports events using the access token it obtains when it registers or renews its tokens. If it cannot renew its tokens, for example because the device has been offline for longer than the maxTimeOfflineInSecs configured on the verifier application, events cannot be delivered.

The fix: bring the device online so the SDK can renew its tokens. Refer to Token validity and offline use.

Some verifications have no eventCopy Anchor Link

What you will find: verification events for a device, but fewer than the number of verifications you know took place.

The SDK does not report an event in the following cases:

• The verification did not return a response. No event is reported when sendProximityPresentationRequest throws an error. This includes a request that times out, and a session that is terminated before the holder responds.
• The event could not be delivered. The SDK sends each event once, in the background, and does not retry. An event is lost if the device is offline when it is sent, or if the app is closed before it is sent.

The fix: check the SDK logs on the device. The SDK logs a message, including the session ID, when an event cannot be delivered or is rejected. If your use case needs a complete record of every verification, record the results your app receives from the SDK in your own systems.

A verification event was recorded long after it happenedCopy Anchor Link

What you will find: an event whose createdAt is significantly later than its timestamp.

The timestamp comes from the device clock, and createdAt is when MATTR VII recorded the event. A large gap means either the device clock was wrong, or the event was delivered some time after the verification. These events can be missing from date-bounded queries you ran before they arrived, because dateFrom and dateTo filter on timestamp.

The fix: if you ran a date-bounded query before the event arrived, run the query again to include it.

The credential did not verifyCopy Anchor Link

What you will find: a CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS event where credentials[].verificationResult.verified is false.

The event name means the exchange completed, not that the credential passed verification. The reason is in credentials[].verificationResult.reason.type. The most common are:

• IssuerNotTrusted: The credential was issued by an issuer that is not on the device's trusted issuer list.
• MobileCredentialExpired or MobileCredentialNotYetValid: The credential is outside its validity period. Compare credentials[].validityInfo with the event timestamp.
• StatusRevoked: The issuer has revoked the credential.

Refer to Handling verification results for the full list of reasons.

The fix: for IssuerNotTrusted, check the trusted issuers configured in your app. Trusted issuers are stored on each device, so a single device with an outdated list fails where others succeed. Group the failures by applicationInstanceId to find it.

The holder did not share everything you requestedCopy Anchor Link

What you will find: a CREDENTIAL_PRESENTATION_PROXIMITY_VERIFICATION_SUCCESS event with entries in credentials[].claimErrors or credentialErrors.

• claimErrors lists requested claims the holder did not return, keyed by namespace and claim name. This does not affect the credential's verified flag.
• credentialErrors lists requested credentials the holder did not return at all, usually because their wallet did not hold a matching credential.

The fix: compare credentialQuery with what was returned. If the same claim is missing across many holders, check that the claim name and namespace in your request are correct for the credential type. Refer to Handling verification results.

You cannot tell which verification belongs to which recordCopy Anchor Link

What you will find: verification events you can trace by device and time, with no way to connect them to a record in your own systems.

Nothing about the holder is recorded in these events. Claim values are never included, so an event describes a verification and not a person.

The fix: record the results your app receives from the SDK in your own systems, together with the time of the verification and the device. You can then match a record to an event using the applicationInstanceId and the event timestamp.

Next stepsCopy Anchor Link