Troubleshooting
common problems and their fixes.

iOS opens an app from a card only through a universal link. Check that https://<your host>/.well-known/apple-app-site-association answers 200 with application/json, no redirect, and has your Team ID and bundle ID; that the app has the Associated Domains capability with applinks:<your host>; and that the host on the card is the same host. Reinstall the app after changing the file. See Card host setup.

Background tag reading needs an iPhone XS or newer with the screen on. iOS pauses it while the camera or Apple Pay is in use and in Airplane Mode. Older iPhones can only read cards inside the app with Test a card.

Check the chip: it must be NTAG215 or NTAG216 (NTAG213 for a link only). iPhones cannot read MIFARE Classic. Hold the card flat against the top back of an iPhone, or the middle back of most Android phones, for a second. On Android, turn on NFC in the system settings. Metal phone cases and some card wallets block NFC.

These writes only go to the card that already carries this card's link. Hold the same card you chose in the app.

The card is blank or damaged, often because it was pulled away during a write. Pair it again from the Card tab. Pairing writes a fresh link; any backup or addresses on that card are gone, so save the backup again.

An NTAG213 is too small for a recovery backup. Use NTAG215 or NTAG216.

The card's link host is not in cardHosts in apps/nfc_recovery/lib/white_label.dart. Add your host and rebuild.

The card's Android record names a package that is not installed. Cards written by Card Studio carry the package from studio/nfc_core.py; change it there to your applicationId (see White label), or re-pair the card in your app.

Use "lost card" in the card prompt: three words of the recovery phrase turn the requirement off at once, or choose the 72-hour switch-off. See Lost card.

Spender cards only approve plain coin payments (ETH, POL, BNB, AVAX, SOL, BTC) on a network that has a limit. Tokens, swaps, dApp requests and approval changes always need an Owner or Backup card. The limit is a rolling 24 hours and counts payments from the moment the card approved them, even if the send failed.

CocoaPods needs a UTF-8 locale. Run export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 in the terminal, then cd ios && pod install. NFC Crypto's Podfile already sets this; the other apps do not.

Build the simulator app for arm64 only. CryptoCard and NFC Recovery already exclude x86_64 for the simulator in their ios/Flutter/*.xcconfig. For NFC Crypto, see Simulator builds.

Set your Apple team. See Set your Apple team.

Turn on NFC Tag Reading (and Associated Domains for NFC Crypto and CryptoCard) for your App ID on developer.apple.com, or let Xcode's automatic signing add them.

iOS caches the launch screen and icon of an installed app. Delete the app from the phone or simulator, run flutter clean, then build and install again. See App icons.

A native file still has the old app name, card host or package. The failing line names the file. If you turned on a swap fee, the test "the shipped config charges no fee" also fails by design; update its expected values.

NFC Crypto and CryptoCard fall back to debug signing when android/key.properties is missing. NFC Recovery always uses debug keys until you add a release signing config. See Android release.

The shipped RPC URLs are public and rate-limited. Put your own provider first in rpcUrls (Networks) and add explorer or Alchemy keys (Configuration).

Set REOWN_PROJECT_ID in .env and build with --dart-define-from-file=.env. Without it, dApp pairing is off.

Set ZEROX_API_KEY or ONEINCH_API_KEY. Without them, EVM swaps use the on-chain router of each network.

Your fee wallet needs a token account for the token being bought. Without it, the swap runs without a fee. See Swap fee → Solana.

A Solana account must hold at least 0.00089088 SOL (rent-exempt minimum). The app explains when a send is below it or would leave less than that behind.

macOS ships Python 3.9. Install a newer one (brew install python or python.org), delete .venv in apps/card_studio and run ./run.sh again. On Windows, install from python.org with "Add python.exe to PATH" ticked.

Plug it in before you start the studio; its LED lights up red. On Windows, install the ACR122U PC/SC driver from ACS. If pyscard could not be installed, the studio runs with the simulated reader only; delete .venv/pyscard-skipped and start again to retry.

Use run.bat, or powershell -ExecutionPolicy Bypass -File .\run.ps1.

It never overwrites a card that carries a recovery backup, and it needs "Overwrite existing link" to replace a link. To reuse a card with a backup, erase it on purpose: type ERASE and tick "destroy the backup".

The terminal window was closed, or the studio was quit. Start it again; each launch has a new address and key.