Troubleshooting

Overview

This guide covers common issues you may encounter when developing and testing with MagicBlock Ephemeral Rollups, along with solutions and workarounds.

Connection Issues

Connection refused to localhost:7799 or localhost:8899

Problem: Tests fail with connection errors:

Error: connect ECONNREFUSED 127.0.0.1:7799

Solutions:

Check if validators are running:

lsof -i :8899  # Base layer
lsof -i :7799  # Ephemeral Rollup

Start validators if not running:

# Terminal 1
mb-test-validator --reset

# Terminal 2
RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

Check validator health:

curl http://127.0.0.1:8899/health
curl http://127.0.0.1:7799/health

View validator logs:

tail -f /tmp/mb-test-validator.log
tail -f /tmp/ephemeral-validator.log

Wrong cluster endpoint configured

Problem: Tests connect to devnet when you expect localnet, or vice versa.Solution:Check your Anchor.toml configuration:

Anchor.toml

[provider]
cluster = "localnet"  # Should match your intended network
wallet = "~/.config/solana/id.json"

Verify environment variables:

echo $EPHEMERAL_PROVIDER_ENDPOINT
echo $ANCHOR_PROVIDER_URL

Expected values for localnet:

EPHEMERAL_PROVIDER_ENDPOINT=http://localhost:7799
ANCHOR_PROVIDER_URL=http://127.0.0.1:8899

ephemeral-validator not found

Problem:

Error: ephemeral-validator is not installed

Solution:Install the ephemeral validator globally:

npm install -g @magicblock-labs/ephemeral-validator

Verify installation:

which ephemeral-validator
ephemeral-validator --version

If using nvm, ensure the global package is accessible:

npm config get prefix
# Should show your nvm node version path

WebSocket connection failed

Problem: Tests timeout or fail with WebSocket errors:

Error: WebSocket connection to 'ws://localhost:7800' failed

Solutions:

Verify WebSocket endpoint configuration:

const providerEphemeralRollup = new anchor.AnchorProvider(
  new anchor.web3.Connection(
    process.env.EPHEMERAL_PROVIDER_ENDPOINT || "http://localhost:7799",
    {
      wsEndpoint: process.env.EPHEMERAL_WS_ENDPOINT || "ws://localhost:7800",
    }
  ),
  anchor.Wallet.local()
);

Check if ephemeral-validator is listening on WS port:

lsof -i :7800

Restart ephemeral-validator with correct ports:

RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

The WebSocket will be available on port 7800 (RPC port + 1).

Build and Deployment Issues

Program already deployed with different address

Problem: Program ID mismatch errors when deploying:

Error: Program <ID> is already deployed at a different address

Solution:Delete existing keypairs and rebuild:

rm -rf target/deploy/*.json
anchor build
anchor deploy --provider.cluster localnet

Update program IDs in:

Anchor.toml
lib.rs (declare_id! macro)
Any test files

Anchor build fails with dependency errors

Problem:

error: package `ephemeral-rollups-sdk` cannot be built

Solutions:

Update dependencies:

cargo update

Check Rust version:

rustc --version
# Should be 1.85.0 or later
rustup update

Verify Anchor version:

anchor --version
# Should be 0.32.1
avm use 0.32.1

Clean and rebuild:

anchor clean
cargo clean
anchor build

Deployment fails with insufficient funds

Problem:

Error: Account <address> has insufficient funds for rent

Solution:For localnet, airdrop SOL:

solana airdrop 100 --url http://localhost:8899

For devnet:

solana airdrop 2 --url https://api.devnet.solana.com

Check balance:

solana balance --url http://localhost:8899

Anchor test starts wrong validator

Problem: anchor test starts its own validator instead of using the running one.Solution:Use the --skip-local-validator flag:

anchor test --skip-local-validator --skip-build --skip-deploy

Or set in Anchor.toml:

[scripts]
test = "./fullstack-test.sh --skip-local-validator"

The test script will automatically detect and use running validators.

Delegation Issues

Account not found after delegation

Problem: Tests fail immediately after delegation:

Error: Account not found

Solution:Add a delay after delegation to allow propagation:

it("Delegate counter to ER", async () => {
  // ... delegation code
  await provider.sendAndConfirm(tx, [provider.wallet.payer]);
  
  // Wait for delegation to propagate
  await new Promise((resolve) => setTimeout(resolve, 3000));
});

A 2-3 second delay is typically sufficient for delegation to complete.

Delegation instruction missing accounts

Problem:

Error: Missing required account for delegation

Solution:For localnet, include the validator identity in remaining accounts:

const remainingAccounts =
  providerEphemeralRollup.connection.rpcEndpoint.includes("localhost") ||
  providerEphemeralRollup.connection.rpcEndpoint.includes("127.0.0.1")
    ? [
        {
          pubkey: new web3.PublicKey("mAGicPQYBMvcYveUZA5F5UNNwyHvfYh5xkLS2Fr1mev"),
          isSigner: false,
          isWritable: false,
        },
      ]
    : [];

let tx = await program.methods
  .delegate()
  .accounts({ /* ... */ })
  .remainingAccounts(remainingAccounts)
  .transaction();

Delegation fails with 'Invalid seeds'

Problem:

Error: Invalid seeds for PDA derivation

Solution:Ensure PDA seeds match between delegation and program:

// In your program
const TEST_PDA_SEED: &[u8] = b"counter";

pub fn delegate(ctx: Context<DelegateInput>) -> Result<()> {
    let pda_seeds: &[&[u8]] = &[TEST_PDA_SEED];
    
    delegate_account(
        // ... accounts
        pda_seeds,
        0,     // max delegation lifetime
        30000, // commit interval in ms
    )?;
    Ok(())
}

Verify PDA derivation in tests:

const [counterPDA] = anchor.web3.PublicKey.findProgramAddressSync(
  [Buffer.from("counter")],  // Must match TEST_PDA_SEED
  program.programId
);

Cannot delegate already delegated account

Problem:

Error: Account is already delegated

Solution:Undelegate before re-delegating:

import { createUndelegateInstruction } from "@magicblock-labs/ephemeral-rollups-sdk";

const ix = createUndelegateInstruction({
  payer: provider.wallet.publicKey,
  delegatedAccount: pda,
  ownerProgram: program.programId,
  reimbursement: provider.wallet.publicKey,
});

const tx = new anchor.web3.Transaction().add(ix);
await provider.sendAndConfirm(tx);

Or reset the validator:

pkill -f "ephemeral-validator"
rm -rf magicblock-test-storage

RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

Commit and State Issues

Commit transaction fails

Problem:

Error: Transaction simulation failed

Solution:Use skipPreflight: true when committing:

const txHash = await providerEphemeralRollup.sendAndConfirm(tx, [], {
  skipPreflight: true,
});

Commits may fail simulation but still succeed on-chain.

GetCommitmentSignature timeout

Problem:

Error: Timeout waiting for commitment signature

Solution:Increase timeout or check base layer connectivity:

import { GetCommitmentSignature } from "@magicblock-labs/ephemeral-rollups-sdk";

// Wait longer for commitment
await new Promise((resolve) => setTimeout(resolve, 5000));

const txCommitSgn = await GetCommitmentSignature(
  txHash,
  providerEphemeralRollup.connection
);

Verify base layer is reachable:

curl http://127.0.0.1:8899/health

State mismatch between ER and base layer

Problem: Account state differs between Ephemeral Rollup and base layer.Solution:

Explicitly commit changes:

let tx = await program.methods
  .commit()
  .accounts({
    payer: providerEphemeralRollup.wallet.publicKey,
  })
  .transaction();

await providerEphemeralRollup.sendAndConfirm(tx, [], {
  skipPreflight: true,
});

Wait for commitment to finalize:

const txCommitSgn = await GetCommitmentSignature(
  txHash,
  providerEphemeralRollup.connection
);

// Wait for confirmation on base layer
await provider.connection.confirmTransaction(txCommitSgn, "confirmed");

Verify commit interval in delegation:

delegate_account(
    // ... accounts
    pda_seeds,
    0,
    30000, // Commit every 30 seconds
)?;

Version Compatibility

Solana version mismatch

Problem:

Error: Solana version mismatch

Solution:Use the correct Solana version (2.3.13):

agave-install list
agave-install init 2.3.13
solana --version

Update PATH:

export PATH="~/.local/share/solana/install/active_release/bin:$PATH"

Anchor version incompatibility

Problem:

Error: Anchor version 0.30.0 is not compatible

Solution:Install and use Anchor 0.32.1:

avm install 0.32.1
avm use 0.32.1
anchor --version

Update Anchor.toml:

[toolchain]
anchor_version = "0.32.1"

SDK version mismatch

Problem:

Error: Cannot find module '@magicblock-labs/ephemeral-rollups-sdk'

Solution:Install the correct SDK version:

yarn add @magicblock-labs/ephemeral-rollups-sdk@0.6.5

For Rust:

cargo add ephemeral-rollups-sdk

Verify in package.json:

{
  "dependencies": {
    "@coral-xyz/anchor": "0.32.1",
    "@magicblock-labs/ephemeral-rollups-sdk": "0.6.5"
  }
}

Node.js version issues

Problem:

Error: This version of Node.js requires a different ABI

Solution:Use Node.js v24.10.0 or compatible:

# Using nvm
nvm install 24.10.0
nvm use 24.10.0
node --version

Reinstall dependencies:

rm -rf node_modules yarn.lock
yarn install

Test Execution Issues

Tests timeout

Problem:

Error: Timeout of 2000ms exceeded

Solution:Increase mocha timeout:

yarn ts-mocha --colors -p ./tsconfig.json -t 1000000 tests/**/*.ts

Or in test files:

describe("anchor-counter", function () {
  this.timeout(1000000); // 1000 seconds
  
  // ... tests
});

Tests pass locally but fail in CI

Problem: Tests work on local machine but fail in continuous integration.Solution:

Ensure validators start properly:

.github/workflows/test.yml

- name: Wait for validators
  run: |
    for i in {1..60}; do
      if curl -s http://127.0.0.1:8899/health > /dev/null; then
        echo "Validator ready"
        break
      fi
      sleep 1
    done

Add sufficient delays:

// After delegation
await new Promise((resolve) => setTimeout(resolve, 5000));

Use —skip-local-validator in CI:

anchor test --skip-build --skip-deploy --skip-local-validator

Multiple validator instances running

Problem: Multiple validators interfere with each other.Solution:Kill all validator processes:

pkill -f "solana-test-validator"
pkill -f "mb-test-validator"
pkill -f "ephemeral-validator"

Clean ledger directories:

rm -rf test-ledger test-ledger-magicblock magicblock-test-storage

Restart validators:

mb-test-validator --reset

Transaction signature verification failed

Problem:

Error: Transaction signature verification failed

Solution:Ensure wallet is properly configured:

const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);

// Verify wallet
console.log("Wallet:", provider.wallet.publicKey.toString());

Check wallet file exists:

ls -la ~/.config/solana/id.json

Generate if missing:

solana-keygen new --no-bip39-passphrase --outfile ~/.config/solana/id.json

Performance Issues

Slow transaction confirmation

Problem: Transactions take longer than expected to confirm.Solution:

Use appropriate commitment levels:

// Base layer - use 'confirmed'
const txHash = await provider.sendAndConfirm(tx, [provider.wallet.payer], {
  skipPreflight: true,
  commitment: "confirmed",
});

// ER - usually faster
const txHash = await providerEphemeralRollup.sendAndConfirm(tx);

Check network congestion:

solana block-time --url http://localhost:8899

Monitor validator performance:

tail -f /tmp/ephemeral-validator.log | grep "slot"

High memory usage

Problem: Validators consume excessive memory.Solution:Restart validators periodically:

pkill -f "ephemeral-validator"
rm -rf magicblock-test-storage

RUST_LOG=info ephemeral-validator \
  --remotes "http://127.0.0.1:8899" \
  --remotes "ws://127.0.0.1:8900" \
  -l "127.0.0.1:7799" \
  --reset

Limit ledger size:

mb-test-validator --reset --limit-ledger-size 50000000

Getting Help

If you encounter issues not covered here:

Check validator logs:

tail -f /tmp/mb-test-validator.log
tail -f /tmp/ephemeral-validator.log

Enable debug logging:
```
RUST_LOG=debug anchor test
```
Join the community:
- MagicBlock Discord
- GitHub Issues
Review documentation:
- MagicBlock Documentation
- Local Development Guide

Getting Started

Core Concepts

Framework Examples

Advanced Examples

Development

Overview

Connection Issues

Build and Deployment Issues

Delegation Issues

Commit and State Issues

Version Compatibility

Test Execution Issues

Performance Issues

Getting Help

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Framework Examples

Advanced Examples

Development

Documentation Index

​Overview

​Connection Issues

​Build and Deployment Issues

​Delegation Issues

​Commit and State Issues

​Version Compatibility

​Test Execution Issues

​Performance Issues

​Getting Help

​Next Steps

Build docs developers (and LLMs) love

Overview

Connection Issues

Build and Deployment Issues

Delegation Issues

Commit and State Issues

Version Compatibility

Test Execution Issues

Performance Issues

Getting Help

Next Steps