Troubleshooting
messages and their fixes.

01Build and run

"The current Dart SDK version is …" / version solving failed

The package needs Dart 3.11.1 or newer. Run flutter upgrade, then flutter pub get.

Strange errors after changing packages or the bundle ID

flutter clean
flutter pub get

On iOS or macOS also run pod install in ios/ or macos/.

flutter run -d windows or -d linux does not work

Expected. The package has no Windows or Linux platform folder (Platforms).

A test fails after I edited text

test/docs_are_current_test.dart fails when DOCS/COMPATIBILITY.md or DOCS/AUTHORITIES.md no longer match the code. Run dart run tool/generate_docs.dart. test/language_guard_test.dart fails if new copy promises a return; reword it.

Google Play rejects the bundle as debug-signed

Release builds use the debug key until you add your own (how).

02Endpoint and keystore

"Public endpoint in use"

No endpoint of your own is saved for the selected cluster. Add one in Settings → Your RPC endpoints (how).

"The endpoint must be https"

Only https:// URLs are accepted, except localhost or 127.0.0.1 for a local validator.

"The keystore refused the write, so this endpoint is in use for this session only"

On the web: the page is not served over HTTPS. Serve it over HTTPS (localhost during flutter run is fine). On macOS: add the Keychain Sharing capability (how).

"Keystore unavailable"

The OS store could not be read, so the forge fell back to the public endpoint. Same fixes as above; then save the endpoint again.

Holders, Expiry, Approvals or Fees say the list is unread

The public endpoint refuses getProgramAccounts. Use your own endpoint. The console deliberately says unread rather than zero.

Requests fail or time out now and then

Your provider's free tier may be rate limiting you. Try again, or move to a higher plan with your provider.

03Building a token

"The mint address and the fee payer cannot be the same account."

The mint address must be a fresh keypair from solana-keygen, not your wallet (how).

"A fee is set but no withdraw authority holds it."

Every withheld fee would be locked forever. On step 4 set the Withdraw withheld authority.

"Accounts start frozen but no freeze authority is set…"

With Default account state: frozen, nobody could ever be thawed. Set a freeze authority or switch the extension off.

"Metadata needs an update authority at creation."

Set a metadata update authority on step 4. You can renounce it later in the console, but then no expiry can be extended.

"The token name is longer than 128 bytes" (or symbol 32, URI 256)

Shorten it. For long descriptions, put them in the JSON your metadata URI points to.

The Forge button stays disabled

Either something on the review step needs fixing (Show me what to fix), or step 5 was not acknowledged, or you changed something after acknowledging. Read step 5 again and press I have read what this breaks.

I cannot select mainnet

Switch on Allow mainnet in Settings → Network.

"Run the mainnet preflight simulation before signing."

On mainnet, press Simulate on the handoff screen first. Signing is offered only after a successful simulation.

04On chain

Blockhash not found / the simulation fails after a wait

The transaction's recent blockhash expired before it was signed and sent. Go back and build it again, then sign and submit promptly. Plan multisig rounds so all signers are ready.

custom program error: 0x25

NonTransferable: a transfer on a non-transferable mint. On Membership, Licence and Pass tokens only a burn can revoke (Revoke).

"This transaction is … bytes, over the 1232-byte limit."

Shorten the metadata (name, URI, custom fields). Large issue lists are split automatically.

The cluster rejects the mint for lack of compute

Raise Compute units requested in Settings → Transactions (default 200,000, maximum 1,400,000).

A confirmed transaction shows "Signature recorded, not verified"

Press Check it against the chain in the audit trail. It asks the cluster the transaction was sent to.

Insufficient funds

The fee payer needs SOL for rent and fees. Use Read its balance on the build sheet; on devnet, airdrop test SOL (how).

05Settings

The whole app says "This instance is closed"

Maintenance mode is on, and in version 0.1.0 it hides Settings too. Clear the app's stored data (web: clear site data for the forge's address; other platforms: reinstall). This resets settings, venue checks and the local audit trail (details).

After "Pull it now" some of my settings are gone

A pull replaces the whole settings document; fields missing from the file return to defaults. Add every field to the published file (format).

"The config URL must be https."

Host the file on HTTPS. The pull sends no credential.

"Nothing usable at that URL."

The URL did not answer with status 200 and a JSON object. Open it in a browser and check it is valid JSON.