Troubleshooting attestation

For everyone working on attestation: mobile developers, console admins, platform engineers and backend developers. Start from where you see the symptom. This page tells you which component is at fault, the likely cause and the fix, and links to the page with the detail.

Each attestation page has its own troubleshooting table for problems within its component. This page covers the failures that show up in one place but are caused in another.

Find the failing stage

Check the stages in the order of the setup path. The first check that fails tells you where to look:

Failures that cross components

These are the failures most often met during setup. Each one shows up in one component and is fixed in another.

The app reports verifierUnavailable

• Shows up as: Swift failed(.verifierUnavailable, …), Kotlin Failed(VerifierUnavailable, …), Flutter and React Native VERIFIER_UNAVAILABLE, every time. Requests go out without the header. On the Status tab, the environment’s row reads host not registered or pin mismatch.
• Cause: the SDKs pin their calls to the verifier, and in strict mode they never reach a host that isn’t registered and pinned in the same TrustPin project. Other causes: the verifier’s certificate was renewed with a new key and the pin wasn’t updated, the pinning instance wasn’t set up before attestation, the verifier URL in the app is wrong, or the verifier is down. On Android, a release build on an emulator or a non-OEM operating system image is refused by the pinning SDK.
• Fix: register and pin the verifier’s domain, then Publish config, and run Check now until Pinned for the SDKs passes. For the other causes, see the SDK page’s troubleshooting: iOS and macOS, Android.

Attestation fails with app_not_allowed

• Shows up as: the app reports attestationFailed with the reason app_not_allowed (Flutter and React Native: ATTESTATION_FAILED). The verifier answers 403 app_not_allowed, in both modes. In monitor mode, a listed Android package signed with an unlisted certificate gets a token with tp.result fail and app_not_allowed instead.
• Cause: the policy doesn’t describe the build that runs:
  • Apple: the Team ID or Bundle ID differs from the build’s.
  • Android: the package name differs, for example a debug build with an applicationIdSuffix, or the build is signed with a certificate the policy doesn’t list. Builds installed from Google Play are signed with the Play app signing key, not your upload key.
  • Simulators and emulators: a debug token presents the app ID of the build. On a simulator build without a signing team, set TRUSTPIN_DEBUG_APP_ID.
  • The policy change that adds the app was saved but not published, or was published less than one refresh interval (5 minutes) ago.
  • The app is configured with a verifier that serves another TrustPin project.
• Fix: compare the policy with the build: codesign -d --entitlements - on Apple, apksigner verify --print-certs on Android. See Apple apps and Android apps, then Sign and publish.

Your API refuses the token: binding mismatch

• Shows up as: bound to another session in your API’s attestation refused: log line, or in the gateway’s log. The app reaches ready and sends the header.
• Cause: your API hashes a different value from the one the app bound. Typical causes: the API drops the scheme (Bearer ) before hashing, a proxy or gateway rewrites the Authorization header, or the app uses fixed binding (setTokenBinding) while the API hashes Authorization.
• Fix: hash the header value exactly as received, scheme included, or the value agreed on for fixed binding. See Binding.

A staging token reaches the production API

• Shows up as: ERR_JWKS_NO_MATCHING_KEY, or ERR_JWT_CLAIM_VALIDATION_FAILED unexpected "iss", in your API’s log, for tokens from one app build only. Gateways log unknown kid or wrong iss.
• Cause: each environment has its own verifier, with its own signing keys and issuer, while sharing one policy. A build configured with the staging verifier’s URL that calls the production API, or the other way round, presents a token the API can’t verify.
• Fix: point each build at its own environment’s verifier, and give each API the values from the Go-live guide with its own Environment picked. See Staging and production.

The same ERR_JWKS_NO_MATCHING_KEY appears for tokens issued before a restart of a verifier without TRUSTPIN_TOKEN_SIGNING_KEYS, or signed by a key removed before the end of a rotation. See Signing keys.

Debug tokens don’t work, or work where they shouldn’t

A debug token works only when both hold: the published policy has Allow debug tokens on, and the verifier the app calls has the token’s hash in TRUSTPIN_DEBUG_TOKEN_HASHES. Production verifiers have no hashes, so they never accept one.

Clocks out of step

• Shows up as: ERR_JWT_EXPIRED in your API’s log for tokens the app just received; a [warn] on the clock line of attest-verifier check; a note on Challenge and applied policy in Check now that the verifier’s clock is off; Play Integrity refusals with token_too_old.
• Cause: your API’s host or the verifier’s host is off. Your API accepts 60 seconds of skew, and check warns beyond 30 seconds. The device’s clock doesn’t matter: the SDKs schedule against the verifier’s clock.
• Fix: run NTP on every API and verifier host.

The verifier exits with code 3

• Shows up as: the verifier, or attest-verifier check, exits with code 3.
• Cause: no policy is published for the project in TRUSTPIN_ORG_ID and TRUSTPIN_PROJECT_ID. The first publish must be made in the console; the CLI refuses it.
• Fix: on the Policy tab, Sign and publish, then start the verifier again. See Signing and publishing.

Play Integrity credentials are missing

• Shows up as: a restarted verifier exits with code 2, naming the Play Integrity credentials. A running verifier stays on the previous policy version, /readyz reports degraded with policy refresh incompatible, and the Status tab row reads policy vN applied, vM published.
• Cause: a policy whose Evidence is Both or Play Integrity only was published before the verifier had TRUSTPIN_PLAY_INTEGRITY_CREDENTIALS.
• Fix: set the credential on every instance of every environment, and restart. Deploy configuration before the policy that needs it. See Policy updates.

With Either, a verifier without the credential keeps working: Android devices pass on Key Attestation alone.

Every device attests again after a deploy

• Shows up as: a spike of attestations, Apple and Google calls and Play Integrity quota after a verifier deploy; refreshes answer 401 invalid_key_certificate.
• Cause: TRUSTPIN_TOKEN_SIGNING_KEYS changed, was dropped (so the verifier generates keys in memory at each start), or differs between instances.
• Fix: restore the previous list, give every instance of the environment the same value, and rotate in three steps.

A policy change doesn’t seem to apply

In the app

Read the SDK’s state and turn on debug logging; the SDK page explains how. Error names follow each language:

After a failure, the SDK tries again only after the retry time in the failed state, at the next request, getToken() or prefetch(). A refusal makes the device wait TRUSTPIN_REFUSAL_RETRY_AFTER (10 minutes by default), and that wait survives a relaunch. Once the cause is fixed, reset() ends it.

Requests arrive without the header

The SDKs never block a request: without a token, it goes out without the header. Your API logs outcome missing.

Reason codes

Reason codes appear in the app’s attestationFailed reasons, in the verifier’s 403 answers and log, and in tp.reasons of tokens issued in monitor mode. They come in two classes.

Binding failures mean the evidence doesn’t match its device key, challenge or app. They never yield a token, in either mode, and no policy setting relaxes them. A sustained rate fires the AttestVerifierForgeries alert (Alerts and dashboard).

Policy failures mean the device or app doesn’t meet a setting of your policy. In monitor mode the device still gets a token, with tp.result fail; in enforce mode it gets 403 attestation_failed. Each setting is described in Setting up apps and the policy, and the rollout page says how to judge each reason before enforcing.

The SDKs may report their own reason when the verifier gave none: http_<status> for an answer without a reason, invalid_key and invalid_input. too_many_attestations is the verifier’s per-key limit, below.

In the verifier’s answers

The SDK reacts to each error on its own; you see these codes in the verifier’s log, in the trustpin_attest_http_requests_total metric by code, and in the reasons the app reports.

401 invalid_token comes only from POST /v1/assertion, which your API calls; see Assertions for sensitive operations. The full list is in the verifier API reference.

In the verifier’s operation

Exit codes

attest-verifier check and the verifier exit with the same codes. check prints a [FAIL] line for each problem.

Read every [warn] line too. The usual ones: the clock is more than 30 seconds off, the signing keys or challenge secrets are generated in memory, the store is memory:// with several instances, or an unknown TRUSTPIN_* variable, usually a misspelling.

Readiness

GET /readyz on port 9090 answers ok, degraded (serving, but needs attention) or unavailable (no traffic). Send the monitor key to see which check fails.

The causes and fixes for each are in Readiness. If probes from outside the container can’t connect at all, set TRUSTPIN_MONITOR_LISTEN_ADDR=:9090 with TRUSTPIN_MONITOR_API_KEY.

On the console’s Status tab

Check now, under Verifier checks, connects to the environment’s verifier URL as an app would. Each step passes, warns or fails, and the environment’s row sums them up.

The Verifier fleet card reads Never fetched or No recent fetch when no policy fetch has been logged. Fetch logs arrive a few hours late, per UTC day, so a verifier deployed today can take a while to appear. Check now gives the exact state at once.

In your API’s log

The checkAttestation middleware logs one attestation line per request, with outcome, and an attestation refused: line when a token fails verification. A gateway recipe logs trustpin attestation rejected: <reason>.

The full table is in Verifying tokens in your API.

At the gateway

The gateway recipes check the same things as your API, with these differences, which explain most surprises:

The rest is in Checking tokens at the gateway.

Before you contact support

TrustPin sees no attestation traffic, so the answers are in your own logs. Collect these before writing to support@trustpin.cloud:

• the verifier version (attest-verifier version), the output of attest-verifier check, and the /readyz body;
• the Check now result for the environment;
• the app’s SDK and version, its state and error, with the reasons, and the time of the attempt;
• the verifier’s log lines for that time (they carry request_id and the first characters of the device key, never tokens or evidence), and your API’s attestation line.

Never send a valid token, a debug token or a secret.

Next steps

• Attestation FAQ
• Operating the verifier: metrics, alerts and incident response
• Rolling out: monitor to enforce