ResourcesTroubleshooting

Troubleshooting

Common issues and solutions.

SDK Issues

”Vault not found”

Problem: Trying to use a vault that does not exist for the selected mint.

Solution:

await client.initVault(tokenMint);

“Insufficient funds”

Problem: Not enough available balance for the operation.

Solution:

const vault = await client.getVault(tokenMint);
console.log("Available:", vault?.available.toString());
console.log("Reserved:", vault?.reserved.toString());
 
await client.deposit(amount, tokenMint);

“Schedule not active”

Problem: Trying to act on a paused or cancelled schedule.

Solution:

const schedule = await client.getSchedule(schedulePda);
console.log("Status:", schedule?.status);
 
if (schedule?.status === "Paused") {
  await client.pauseSchedule(schedulePda, false);
}

Coordinator Issues

”ECONNREFUSED” when registering

Problem: Coordinator is not running or not reachable.

Solution:

cd coordinator
npm run dev

“429 Too Many Requests”

Problem: The coordinator’s rate limiter rejected the request.

Solution:

  • back off and retry after the indicated delay
  • avoid repeatedly resubmitting the same registration payload
  • if you operate the coordinator, review the configured rate-limit budgets

”Database connection error”

Problem: PostgreSQL is not configured correctly or is unavailable.

Solution:

pg_isready
 
cd coordinator
npm run db:migrate

“ER authority keypair not found”

Problem: The coordinator cannot load the ER authority signer.

Solution:

solana-keygen new -o er-authority-keypair.json

Then point the coordinator at the file or provide ER_AUTHORITY_KEYPAIR_JSON / ER_AUTHORITY_KEYPAIR_B64.

Transaction Issues

”Blockhash not found”

Problem: The transaction expired before confirmation.

Solution: Retry the transaction so the wallet signs with a fresh blockhash.

”Insufficient funds for fees”

Problem: The wallet does not have enough SOL for transaction fees.

Solution:

solana airdrop 2

Program Issues

”Program not found”

Problem: Wrong program ID or missing deployment.

Solution:

  • verify the deployed program ID
  • verify the SDK / app is pointed at the correct cluster
  • redeploy if needed

”Invalid account”

Problem: A PDA or account owner does not match what the instruction expects.

Solution:

  • derive PDAs with SDK helpers
  • make sure vault PDAs include both employer and token mint
  • make sure schedule PDAs are derived from the vault PDA and scheduleId

Merkle Issues

”Invalid Merkle proof”

Problem: The provided proof does not match the stored root.

Solution:

const { root, proofs } = buildMerkleTree(recipients);

Verify you rebuilt the tree from the exact same ordered recipient list.

”Recipient not found”

Problem: The address is not part of the original schedule payload.

Solution:

  • confirm the recipient is in the original list
  • confirm the amount matches exactly
  • rebuild proofs from the same ordered list used during registration

Getting Help

FAQContributing