Troubleshooting
Common errors and how to fix them
SolanaClusterNotConfiguredException
The
Fix: Confirm the spelling (case-insensitive, but must match exactly otherwise), or add the missing entry — see Clusters.
The
cluster value on an operation (or Solana:DefaultCluster) doesn't match
any key under Solana:Clusters and isn't one of the well-known names
(mainnet-beta, devnet, testnet).
Fix: Confirm the spelling (case-insensitive, but must match exactly otherwise), or add the missing entry — see Clusters.
SolanaInvalidKeyMaterialException
The credential resolved by
Fix: Re-export the key from solana-keygen (
The credential resolved by
credentialID isn't a valid 64-byte base58 secret key or a
64-element JSON byte array.
Fix: Re-export the key from solana-keygen (
solana-keygen new /
cat id.json) or Phantom's private-key export, and re-store it in the vault unmodified —
see Signing & Credentials. A common mistake is storing
only the 32-byte seed instead of the full 64-byte expanded key.
"No signing credential configured"
Fix: Set
credentialID is unset, or the vault entry it points to resolved to an empty value, on one
of the 6 signing operations.
Fix: Set
credentialID to a valid CRYPTO_WALLET vault
entry. Run wallet/getPublicKey to confirm it resolves before
retrying the write operation.
Invalid address/mint/signature format
Solana addresses, mints, and signatures are base58-encoded. A malformed value (wrong alphabet, wrong length) is rejected by the RPC node or by Solnet's own base58 decoding before the RPC call.
Fix: Double-check the value was copied in full and hasn't been base64-encoded or truncated by an upstream step.
Solana addresses, mints, and signatures are base58-encoded. A malformed value (wrong alphabet, wrong length) is rejected by the RPC node or by Solnet's own base58 decoding before the RPC call.
Fix: Double-check the value was copied in full and hasn't been base64-encoded or truncated by an upstream step.
RPC rate limiting (HTTP 429)
The public
Fix: This node already retries automatically up to 3 times, honoring the response's
The public
api.mainnet-beta.solana.com endpoint in particular rate-limits aggressively.
Fix: This node already retries automatically up to 3 times, honoring the response's
Retry-After header when present (falling back to 2 × attempt
seconds otherwise). If you still see 429s surfacing as errors, reduce call frequency, batch reads
where possible, or switch to a paid RPC provider via RpcUrlCredentialID — see
Clusters.
token/transfer fails with an ATA-not-found style error
The destination owner has no Associated Token Account for the mint yet —
Fix: Call
The destination owner has no Associated Token Account for the mint yet —
transfer does
not create one.
Fix: Call
token/createAta for the destination owner first — see
the Examples page's onboarding pattern. It's safe to call
unconditionally since it's idempotent.
staking/delegate fails against a fresh stake account
Fix: Stake account creation isn't implemented on this node yet; see Roadmap. Create and initialize the account with another tool first.
delegate requires an already-initialized stake account — it does not create one.
Fix: Stake account creation isn't implemented on this node yet; see Roadmap. Create and initialize the account with another tool first.
nft/getAsset returns empty name/uri
This is expected, not a bug — this operation resolves ownership only and does not decode Metaplex metadata (no maintained .NET Metaplex library exists for either standard).
Fix: Use an external Metaplex-aware indexer (e.g. Helius DAS API) for human-readable NFT metadata; see NFT Operations.
This is expected, not a bug — this operation resolves ownership only and does not decode Metaplex metadata (no maintained .NET Metaplex library exists for either standard).
Fix: Use an external Metaplex-aware indexer (e.g. Helius DAS API) for human-readable NFT metadata; see NFT Operations.
Attempting an unimplemented operation
Only 17 of the design's 47 catalogued operations are routed — anything else (account creation, token mint, generic program instruction calls, stake account creation, etc.) falls through to a generic "operation not found" result.
Fix: See Roadmap for what's planned and why it isn't here yet.
Only 17 of the design's 47 catalogued operations are routed — anything else (account creation, token mint, generic program instruction calls, stake account creation, etc.) falls through to a generic "operation not found" result.
Fix: See Roadmap for what's planned and why it isn't here yet.