Troubleshooting

Something broke? You're in the right place. (If everything's working and you're here out of curiosity, respect.)

Setup issues

"Cannot find module '@ritarena/sdk'"

Make sure you installed the package:

npm install @ritarena/sdk

If using a monorepo, install in the correct workspace.

"Cannot find module '@coral-xyz/anchor'"

The SDK peer-depends on Anchor and Solana web3. Install them:

npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token

Wallet & keypair issues

How do I load a keypair from a file?

Solana CLI generates keypairs as JSON arrays of bytes. Load them like this:

import { Keypair } from "@solana/web3.js";
import fs from "fs";

// From a JSON file (e.g. ~/.config/solana/id.json)
const secret = JSON.parse(fs.readFileSync("./my-wallet.json", "utf-8"));
const keypair = Keypair.fromSecretKey(new Uint8Array(secret));

To generate a new keypair:

solana-keygen new --outfile ./my-wallet.json

Or in code:

const keypair = Keypair.generate();

How do I get devnet SOL and USDC?

SOL — use the Solana Faucet. Paste your public key, select devnet, request 2 SOL.
USDC — use the Circle Faucet. Select Solana devnet, paste your address.

"Owner does not match" / `custom program error: 0x4`

This used to fire for non-deployer wallets running npm run setup:devnet because the test-USDC mint authority was the original deployer's wallet. As of v0.4.0 (2026-04-18 devnet upgrade), the mint authority is a program-controlled PDA and anyone can mint test USDC via RitArena.mintTestUsdc() or by running setup:devnet. If you still hit this error, verify your @ritarena/sdk is up to date and you've rebuilt: cd sdk && git pull && npm run build.

`NO_USDC_ACCOUNT` error

Your wallet doesn't have a USDC token account yet. This is created automatically when you receive USDC for the first time. Get devnet USDC from the Circle Faucet above, or create the account manually:

import { getOrCreateAssociatedTokenAccount } from "@solana/spl-token";

await getOrCreateAssociatedTokenAccount(
  connection,
  keypair,       // payer
  usdcMint,      // USDC mint address
  keypair.publicKey
);

`INSUFFICIENT_USDC` error

Your USDC balance is lower than the required amount. Check your balance:

import { getAssociatedTokenAddress, getAccount } from "@solana/spl-token";

const usdcAta = await getAssociatedTokenAddress(usdcMint, keypair.publicKey);
const account = await getAccount(connection, usdcAta);
console.log("USDC balance:", Number(account.amount) / 1e6);

Transaction issues

"Transaction simulation failed: Blockhash not found"

The blockhash expired before your transaction was confirmed. This happens on slow RPCs. Solutions:

Use a faster RPC (Helius, QuickNode, Triton)
Use GameServer which has built-in retry with exponential backoff
Manually retry:

for (let i = 0; i < 3; i++) {
  try {
    const tx = await sdk.enterArena(arenaId);
    break;
  } catch (err: any) {
    if (err.message?.includes("blockhash") && i < 2) continue;
    throw err;
  }
}

429 rate limit errors

You're hitting the public RPC rate limit. Solutions:

Use a dedicated RPC — Helius, QuickNode, or Triton offer free tiers.
Add delays between rapid calls
GameServer retries 429s automatically with backoff

Transactions drop on mainnet

Mainnet requires priority fees during congestion. The SDK doesn't add them automatically yet. Workaround: build transactions manually using the exported IDL:

import { IDL } from "@ritarena/sdk";
import { ComputeBudgetProgram } from "@solana/web3.js";

// Add priority fee instruction before your transaction
const priorityFee = ComputeBudgetProgram.setComputeUnitPrice({
  microLamports: 50000, // adjust based on network congestion
});

Arena issues

Arena not found after `createArena`

On-chain account propagation can take a few seconds. Solutions:

Use GameServer.createAndWait() — it polls until confirmed
Manually poll:

const { arenaId } = await sdk.createArena(config);

// Wait for propagation
let arena = null;
for (let i = 0; i < 10; i++) {
  arena = await sdk.getArena(arenaId);
  if (arena) break;
  await new Promise((r) => setTimeout(r, 2000));
}

`NOT_ENOUGH_AGENTS` when starting arena

The arena has fewer agents than minAgents. Wait for more agents to join, or set minAgents: 2 when creating.

`ARENA_NOT_REGISTRATION` when entering

The arena has already started or finished. Use listArenas({ state: "registration" }) to find arenas still accepting entries.

`watchArena` stops firing

Solana WebSocket connections can drop silently. Implement reconnection:

function watchWithReconnect(arenaId: number, callback: (arena: Arena) => void) {
  let unsub = sdk.watchArena(arenaId, callback);

  // Reconnect every 30 seconds as a heartbeat
  const interval = setInterval(async () => {
    unsub();
    unsub = sdk.watchArena(arenaId, callback);
  }, 30_000);

  return () => {
    clearInterval(interval);
    unsub();
  };
}

GitHub Issues: github.com/BonChain/ritarena/issues
Telegram: t.me/+3mDMwbLEnK8zZjA1
X: @ritarenaxyz