Skip to main content

Troubleshooting

This document covers common issues encountered when operating zkIdentity, organized by category. Each issue includes symptoms, likely causes, and resolution guidance.

Provider Issues​

Provider Rejection​

Symptoms: Verification completes but the status is "rejected" instead of "verified."

This is not necessarily a system error. Provider rejection means the KYC provider determined the user's identity could not be verified. Common reasons:

ReasonUser Action
Document quality (blurry, cropped, poorly lit)Retake document photo in good lighting
Document expiredUse a valid, unexpired document
Biometric mismatch (selfie does not match document)Ensure the same person completes the selfie step
Unsupported document typeUse a supported document (national ID, passport)
Liveness failureComplete the selfie without using printed photos or screens

Resolution: Inform the user of the reason and advise them to retry with corrected input. The user can initiate a new verification session.

Provider API Errors​

Symptoms: Verification fails with an "error" status. Attestor logs show HTTP errors from the provider.

Common causes:

  • 401 Unauthorized: Invalid or expired API key. Check credentials in your environment configuration.
  • 403 Forbidden: Account suspended or rate limited. Check provider dashboard.
  • 429 Too Many Requests: Rate limit exceeded. Implement backoff.
  • 5xx errors: Provider outage. Check the provider's status page and retry later.

Diagnostic guidance:

  • Check attestor error logs for provider-related errors.
  • Check the provider's status page (Smile ID and Plaid both publish status pages).
  • Test provider connectivity from the attestor environment.

Webhook Not Received​

Symptoms: User completes the provider verification, but the session remains stuck at a pending state.

Common causes:

  1. Firewall blocking inbound traffic from the provider.
  2. Incorrect webhook URL configured in the provider dashboard.
  3. TLS certificate issue on the webhook endpoint.
  4. Provider webhook delivery system experiencing issues.

Resolution:

  • Verify the webhook URL is accessible from the internet.
  • Check the provider dashboard for webhook delivery logs.
  • Check attestor logs for incoming webhook requests.
  • Verify the TLS certificate is valid and not expired.

Proof Generation Issues​

Proof Generation Timeout​

Symptoms: Session stuck in a proof-generating state. Attestor logs show timeout errors.

Common causes:

  1. Insufficient CPU resources (ZK proof generation is computationally intensive).
  2. Provider API unreachable during zkFetch TLS tunnel establishment.
  3. TEE memory pressure.

Resolution:

  • Increase the proof generation timeout setting.
  • Allocate more CPU and memory resources to the attestor.
  • Verify the provider API is reachable from the attestor.

Proof Verification Failure​

Symptoms: The Cartesi rollup rejects the attestation submission.

Possible causes:

  1. Attestor code version mismatch with the rollup verifier.
  2. Corrupted proof data due to network issues.
  3. System clock skew causing timestamp-based proofs to fail.

Resolution:

  • Ensure the attestor version is compatible with the rollup deployment.
  • Enable NTP synchronization to fix clock skew.
  • Investigate network stability between the attestor and the provider.

Session Issues​

Session Expiry​

Symptoms: Sessions frequently expire before completion.

Common causes:

  1. Provider processing time exceeds the session time-to-live.
  2. User abandonment (users start but do not complete the provider flow).
  3. Webhook delivery delay from the provider.

Resolution:

  • Increase the session time-to-live if provider processing regularly exceeds it.
  • Implement user-facing progress indicators to reduce abandonment.
  • Contact the provider if webhook delivery is consistently slow.

Infrastructure Issues​

IPFS Upload Failures​

Symptoms: Attestations complete but the IPFS CID is missing. Logs show Pinata upload errors.

Common causes:

  • Pinata rate limit or plan limit exceeded.
  • Invalid or revoked credentials.
  • Network timeout.

Resolution:

  • Check Pinata dashboard for usage against plan limits.
  • Verify Pinata credentials.
  • Increase upload timeout for slow connections.
  • Upgrade Pinata plan if limits are regularly hit.

Cartesi Rollup Submission Failures​

Symptoms: Proofs are generated but the attestation is not recorded on the rollup.

Common causes:

  1. Attestor wallet has insufficient ETH balance on Arbitrum.
  2. Rollup node is unavailable.
  3. DApp contract is paused.

Resolution:

  • Fund the attestor wallet with ETH on Arbitrum.
  • Verify rollup endpoint availability.
  • Check DApp contract status.

TEE Attestation Failures​

Symptoms: The attestor starts but health checks show TEE errors.

Possible causes:

  1. Server does not have TEE hardware or it is not enabled.
  2. TEE drivers need updating.
  3. TEE features disabled in BIOS.
  4. TEE mode misconfigured (simulation in what should be production).

Resolution:

  • Verify TEE hardware support.
  • Update TEE drivers.
  • Enable TEE features in BIOS if needed.
  • Ensure TEE mode is set to production for production deployments.

Getting Help​

If the troubleshooting steps above do not resolve the issue:

  1. Collect attestor logs and diagnostic information.
  2. Contact the Hadinet Africa team with the diagnostic details.
  • Monitoring -- Setting up alerts to detect issues proactively.
  • Configuration -- Configuration options that may resolve issues.
  • Testing -- Verifying fixes in sandbox mode before production.