Skip to content
GUIDE-0012GuideIn forceversion 1.0.016 October 2026

Troubleshooting ​

This page collects the problems developers connecting to Tamga run into most often, and their fixes.

When to read it: when a verification gives an unexpected result, when a wallet cannot receive or present a credential, or when a registration application comes back.

First: what does the result say? ​

Verification returns a three-valued result (SPEC-API-0001 §2):

outcomeMeaningField to look at first
ACCEPTEDEvery step passed—
REJECTEDThe credential is invalidfailed_step
INDETERMINATEIt could not be checked right now; no judgement on the credentialindeterminate_reason

Do not show REJECTED and INDETERMINATE with the same message. "This credential is invalid" and "I cannot check right now" lead to different decisions (AP2).

"Could not be verified" (INDETERMINATE) ​

indeterminate_reasonCauseFix
STATUS_UNREACHABLEThe credential's status listA compressed, signed list in which each credential has one position that tells whether it is valid, suspended or revoked. could not be downloadedPrefetch status lists (PrefetchStatusCache + regular refresh); do not go to the network at verification time
STATUS_STALEThe cached status list passed the freshness threshold, or was fetched before the anchor. Or your anchor log is old: the list is newer than the latest anchor you know by more than max_anchor_lag_sec (default 3600 s), or the list is not in your anchor log at all (anchors not loaded). Or the list is signed with a status key of the institution that has expired (key renewed, cache old)Shorten the refresh interval. Reload the trust lists and the anchor log (anchors: true) not only at start-up but more often than max_anchor_lag_sec (for example every 10 minutes). Check clock drift (NTP)
SCHEMA_UNREACHABLEThe credential type definition could not be fetchedCache the schema catalogue in advance
CHAIN_UNREACHABLE / INDEXER_STALEThe trust source could not be read, or is staleDownload the trust lists regularly; fetch the new list once next_update has passed
SDK_VERSION_MISMATCHThe library version does not match the rule versionUpdate the @tamga-network/* packages
STATUS_VALUE_UNKNOWNThe status-list value has no defined meaning (4/8-bit external list, application-specific value)Ask the issuer about its list profile; does not occur for Tamga types

If the trust list is stale or cannot be downloaded, trust questions answer UNKNOWN and the result is always INDETERMINATE; never ACCEPTED, never REJECTED.

Rejected (REJECTED) ​

failed_step says which step did not pass (SPEC-API-0001 §1). The most common:

StepMeaningWhere to look
A3The signature chain does not lead to a root in the trust listDid you load the right list and root fingerprints? Are you verifying a test-environment credential against the live list?
A3bThe certificate that signed the credential does not match the institution in issThe institution identity is always derived from the certificate; do not trust the iss value
A3d / A6No proof of holder binding (KB-JWT), or aud, nonce, iat do not matchIs the nonce you verify the one you sent in the request? Are clocks in sync?
A5A disclosure does not match the digests in the credentialThe presentation was altered; ask again
A7The credential has expired (exp) or is not yet valid (nbf)The person should renew the credential with the institution; is your server's clock correct?
C1The institution was not active when the credential was issuedCheck the institution's status history (GUIDE-0006)
C2The institution was not authorised for this credential typeThe institution's type authorisation (GUIDE-0007 §5)
D6The credential is revoked or suspendedAsk the institution that issued it
E3The fields you asked for are outside your registered scopeWiden your scope (GUIDE-0008 §3)

The trust list does not load ​

SymptomCauseFix
Signature does not verifyThe pinned root fingerprint does not match the root that signed the listTake the fingerprint again from tamga.network/trust-anchor; do not mix environments (test / live)
"Unknown format version"The list is in a newer formatThe reader stops on purpose; update the library
Version went backAn old copy is being served (cache, CDN)The reader rejects rollback; clear the cache
External list entries do not appearThe list is stale, its signer does not match the LOTL, or the entry is out of scopeQuestions that depend on the external list answer UNKNOWN; the other lists are not affected (GUIDE-0011)

Wallet: receiving credentials ​

Error (WalletError)CauseFix
tx_code_mismatchWrong PINThe PIN never comes through the same channel as the offer; ask the person for the PIN from the SMS or e-mail
offer_expired / offer_usedThe offer expired or has been usedAsk the institution for a new offer
offer_not_found / invalid_offerThe QR is damaged or not a Tamga offerScan the offer again
trust_errorThe institution or wallet provider is not in the list, or a signature did not verifyRefresh the trust list; check the institution's entry
unsupportedA type this wallet does not support, or a revoked unit ("This wallet has been revoked.")If the unit was revoked, register again
networkNo connectionTry again

Wallet: device attestation and WUA ​

The response fields below depend on the wallet provider; the examples come from one provider (example: the Tamga Wallet provider). Check your own provider's documentation.

  • Registration response says attestation: "software": the wallet provider could not use the device evidence; the unit still registered, at software level. reason tells why: not_configured (the provider has no App ID or roots for that platform), invalid (the evidence did not verify — usually an app identity, Bundle ID or package name different from what the provider expects), unsupported (development build, emulator, unlocked device or a key outside secure hardware). attestation: "none" means no evidence was presented at all (Expo Go, no native module). Registration is never rejected for these reasons.
  • Registered at software level: you are running in Expo Go or without the native key module. Use a development build (GUIDE-0005 §1).
  • WUA expired: check with wuaExpiringSoon before receiving credentials and renew.

Wallet: presenting ​

SymptomCauseFix
"Outside the registered scope" warning on screenThe verifier is not registered, or asks for fields outside its scopeFix the verifier's entry and scope (GUIDE-0008)
Registration certificate does not matchThe organisation identifier in the registration certificate differs from the one in the access certificateBoth must come from the same official identification number (ADR-0026)
Copies ran outNo verifier-specific copy is leftAsk the person; renewal comes from the institution (ADR-0023)
Pseudonym request refusedThe verifier is not registered, or its entry has no pseudonyms settingAdd the pseudonym setting to the entry (ADR-0031)

A registration application came back ​

The registration tool lists all missing or wrong fields at once (kayıt yapılamadı: followed by items). Common ones: identifiers, postal_address, contact, supervisory_authority (how to reach it: form address, e-mail or phone), scopes[…].privacy_policy_uri. Format: GUIDE-0007 §2 and GUIDE-0008 §2.

Service error format ​

Tamga services return errors in the RFC 9457 format; tamga_code is the machine-readable code and detail contains no personal data:

json
{
  "type": "https://docs.tamga.network/errors/schema-not-authorized",
  "title": "The issuer cannot issue this schema",
  "status": 403,
  "tamga_code": "SCHEMA_NOT_AUTHORIZED"
}
  • A rejected credential is not an error: the verification call succeeds (200) and carries the result in the body (AP5).
  • 409: the same Idempotency-Key was sent with a different body.
  • 429: rate limit; wait for Retry-After.

Still not solved? ​

Remove personal data from your log and report the verification_id, the failed_step or indeterminate_reason, and the library version (sdk_version). Running the conformance tests reveals most mismatches: GUIDE-0009.