Troubleshooting Guide

This guide covers common issues with EVM transaction tracing on Sei and gives practical solutions for them.

Common error categories

1. Timeout errors

Error: execution timeout Cause: The tracer execution exceeded the configured timeout. Solutions:

{
  "tracerConfig": {
    "timeout": "120s" // Increase timeout for complex traces
  }
}

Best practices:

Start with shorter timeouts (30s) for testing
Increase the timeout gradually, based on transaction complexity
Use built-in tracers when possible, because they are faster
Optimize JavaScript tracer code for performance

2. Memory limit errors

Error: out of memory or memory limit exceeded Cause: The tracer collected too much data or used memory inefficiently. Solutions:

{
  "tracerConfig": {
    "enableMemory": false, // Disable memory tracing
    "enableStack": false, // Disable stack tracing
    "enableStorage": false // Disable storage tracing
  }
}

Memory-efficient tracer pattern:

{
  "tracer": `{
    // Use counters instead of arrays
    summary: {
      totalGas: 0,
      operationCount: 0,
      expensiveOps: 0
    },

    step: function(log, db) {
      this.summary.totalGas += log.getCost();
      this.summary.operationCount++;

      // Only track expensive operations
      if (log.getCost() > 1000) {
        this.summary.expensiveOps++;
      }
    },

    result: function(ctx, db) {
      return this.summary; // Return summary, not raw data
    }
  }`
}

3. JavaScript tracer errors

Error: SyntaxError or ReferenceError in a JavaScript tracer Common issues:

// ❌ Incorrect - Missing quotes
{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();
      if (op == SSTORE) { // Missing quotes around SSTORE
        // ...
      }
    }
  }`
}

// ✅ Correct - Proper quotes
{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();
      if (op == "SSTORE") { // Quoted properly
        // ...
      }
    }
  }`
}

Debugging JavaScript tracers:

{
  "tracer": `{
    errors: [],

    step: function(log, db) {
      try {
        // Your tracer logic here
        var op = log.op.toString();
        // ...
      } catch (e) {
        this.errors.push({
          error: e.toString(),
          pc: log.getPC(),
          op: log.op.toString()
        });
      }
    },

    result: function(ctx, db) {
      return {
        data: this.data,
        errors: this.errors // Check for errors
      };
    }
  }`
}

4. Network and connection issues

Tracer not allowed / JavaScript tracers disabled

Error:

debug tracer "..." is not allowed; JavaScript tracers are disabled and only native tracers listed in evm.trace_allowed_tracers may be used

Cause: Sei gates which tracers callers may request through TraceConfig.Tracer on the debug_traceCall, debug_traceTransaction, debug_traceBlockByNumber, debug_traceBlockByHash, and debug_traceTransactionProfile endpoints. By default only the native tracers listed in the [evm] trace_allowed_tracers config are accepted, and request-supplied JavaScript tracer source is rejected. This deviates from upstream geth, which accepts JavaScript tracers by default. Solutions:

Use one of the allowlisted native tracers. The shipped default allowlist is:

[evm]
trace_allowed_tracers = ["callTracer", "prestateTracer", "flatCallTracer", "4byteTracer", "noopTracer", "muxTracer"]

If you are an operator and need to permit a native tracer that is not listed, add its name to trace_allowed_tracers. Only native geth tracer names are accepted here; a typo or JavaScript source causes the node to fail at startup. Setting the list to [] disables all named tracers.
To allow request-supplied JavaScript tracer source, an operator must explicitly opt in:
[evm] trace_allow_js_tracers = true
This executes untrusted code in-process and should be kept disabled on public/default RPC nodes. Enabling it does not widen trace_allowed_tracers: native tracer names must still be listed there to be usable.

When using muxTracer, the nested tracer names in TracerConfig are validated recursively against the same allowlist, with a bounded nesting depth of 16. A nested name that is not allowlisted produces a nested debug tracer "..." is not allowed error. Also note that trace_bake_tracers names are validated as native-only at startup, so a non-native or mistyped name there will fail node startup rather than being evaluated as JavaScript.

Error: connection refused or network timeout Solutions:

# Check if node is running
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

# Test with different timeout
curl --connect-timeout 30 --max-time 120 \
  -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x..."],"id":1}' \
  http://localhost:8545

5. Transaction not found

Error: transaction not found Debugging steps:

# 1. Verify transaction exists
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x..."],"id":1}' \
  http://localhost:8545

# 2. Check if transaction is in a finalized block
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x..."],"id":1}' \
  http://localhost:8545

# 3. Ensure node is fully synced
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545

Performance optimization

Tracer performance tips

Limit data collection:

{
  "tracer": `{
    data: [],
    maxEntries: 1000, // Limit data collection

    step: function(log, db) {
      if (this.data.length < this.maxEntries) {
        // Only collect limited data
        this.data.push({
          pc: log.getPC(),
          op: log.op.toString(),
          gas: log.getGas()
        });
      }
    }
  }`
}

Use efficient data structures:

// ❌ Inefficient - Object lookups
{
  "tracer": `{
    operations: {},

    step: function(log, db) {
      var op = log.op.toString();
      if (!this.operations[op]) {
        this.operations[op] = 0;
      }
      this.operations[op]++;
    }
  }`
}

// ✅ Efficient - Direct assignment
{
  "tracer": `{
    operations: {},

    step: function(log, db) {
      var op = log.op.toString();
      this.operations[op] = (this.operations[op] || 0) + 1;
    }
  }`
}

Selective tracing:

{
  "tracer": `{
    step: function(log, db) {
      var op = log.op.toString();

      // Only trace specific operations
      if (op == "SSTORE" || op == "SLOAD" || op == "CALL") {
        // Process only important operations
        this.processOperation(log, db);
      }
    }
  }`
}

Node configuration for better performance

# In your node configuration
[evm]
# Increase trace timeout
trace-timeout = "300s"

# Increase memory limits
trace-memory-limit = "1GB"

# Enable trace caching
trace-cache-size = 1000

Debugging workflows

1. Failed transaction analysis

#!/bin/bash

TX_HASH="0x..."

echo "1. Checking if transaction exists..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionByHash\",\"params\":[\"$TX_HASH\"],\"id\":1}" \
  http://localhost:8545 | jq '.result'

echo "2. Getting transaction receipt..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$TX_HASH\"],\"id\":1}" \
  http://localhost:8545 | jq '.result.status'

echo "3. Tracing transaction..."
curl -s -X POST -H "Content-Type: application/json" \
  --data "{\"jsonrpc\":\"2.0\",\"method\":\"debug_traceTransaction\",\"params\":[\"$TX_HASH\",{\"tracer\":\"callTracer\"}],\"id\":1}" \
  http://localhost:8545 | jq '.result'

2. Gas optimization workflow

// Step 1: Identify expensive operations
const expensiveOpsTracer = `{
  expensive: [],
  threshold: 1000,
  
  step: function(log, db) {
    var cost = log.getCost();
    if (cost > this.threshold) {
      this.expensive.push({
        pc: log.getPC(),
        op: log.op.toString(),
        cost: cost
      });
    }
  },
  
  result: function(ctx, db) {
    this.expensive.sort((a, b) => b.cost - a.cost);
    return {
      totalExpensive: this.expensive.length,
      topExpensive: this.expensive.slice(0, 10)
    };
  }
}`;

// Step 2: Analyze storage operations
const storageTracer = `{
  storageOps: 0,
  storageGas: 0,
  
  step: function(log, db) {
    var op = log.op.toString();
    if (op == "SSTORE" || op == "SLOAD") {
      this.storageOps++;
      this.storageGas += log.getCost();
    }
  },
  
  result: function(ctx, db) {
    return {
      storageOperations: this.storageOps,
      storageGasCost: this.storageGas,
      averageCost: this.storageOps > 0 ? this.storageGas / this.storageOps : 0
    };
  }
}`;

Error code reference

Common HTTP error codes

Code	Error	Solution
400	Bad Request	Check the JSON-RPC format and parameters
404	Not Found	Verify the transaction hash and node sync status
500	Internal Server Error	Check the node logs and resource limits
503	Service Unavailable	The node may be syncing or overloaded

Tracer-specific errors

Error	Cause	Solution
`execution timeout`	The tracer took too long	Increase the timeout or optimize the tracer
`out of memory`	Too much data collected	Reduce data collection or disable memory tracing
`invalid tracer`	JavaScript syntax error	Validate the tracer syntax
`tracer not found`	The built-in tracer does not exist	Check the available tracers

Best practices summary

✅ Do’s

Start simple: Begin with built-in tracers before you write custom JavaScript.
Set timeouts: Always configure appropriate timeouts.
Limit data: Collect only the information that you need.
Test incrementally: Test tracers on simple transactions first.
Monitor resources: Watch memory and CPU usage.
Cache results: Store expensive trace results when possible.

❌ Don’ts

Do not collect everything: Avoid tracing all operations unnecessarily.
Do not ignore errors: Always handle tracer errors gracefully.
Do not use complex logic: Keep tracer step functions simple.
Do not forget timeouts: Never run tracers without timeout limits.
Do not trace in production: Avoid heavy tracing on production nodes.

Getting help

If you have an issue that this guide does not cover:

Check node logs: Look for error messages in your Sei node logs.
Verify the configuration: Make sure that tracing is enabled on your node.
Test connectivity: Confirm that the RPC endpoints are accessible.
Simplify tracers: Try built-in tracers first.
Community support: Ask in the #dev-support channel of the Sei Discord.

When you report an issue, include your tracer code, the transaction hash, and any error messages that you receive. This helps the community help you.

Overview

Essentials

seid CLI

Frontend Development

Smart Contracts

sei-js Library

Videos

Ecosystem Tutorials

Reference

Hardware Wallets

Troubleshooting Guide

Common error categories

1. Timeout errors

2. Memory limit errors

3. JavaScript tracer errors

4. Network and connection issues

Tracer not allowed / JavaScript tracers disabled

5. Transaction not found

Performance optimization

Tracer performance tips

Node configuration for better performance

Debugging workflows

1. Failed transaction analysis

2. Gas optimization workflow

Error code reference

Common HTTP error codes

Tracer-specific errors

Best practices summary

✅ Do’s

❌ Don’ts

Getting help

​Common error categories

​1. Timeout errors

​2. Memory limit errors

​3. JavaScript tracer errors

​4. Network and connection issues

​Tracer not allowed / JavaScript tracers disabled

​5. Transaction not found

​Performance optimization

​Tracer performance tips

​Node configuration for better performance

​Debugging workflows

​1. Failed transaction analysis

​2. Gas optimization workflow

​Error code reference

​Common HTTP error codes

​Tracer-specific errors

​Best practices summary

​✅ Do’s

​❌ Don’ts

​Getting help

Common error categories

1. Timeout errors

2. Memory limit errors

3. JavaScript tracer errors

4. Network and connection issues

Tracer not allowed / JavaScript tracers disabled

5. Transaction not found

Performance optimization

Tracer performance tips

Node configuration for better performance

Debugging workflows

1. Failed transaction analysis

2. Gas optimization workflow

Error code reference

Common HTTP error codes

Tracer-specific errors

Best practices summary

✅ Do’s

❌ Don’ts

Getting help