Troubleshooting

Solutions to common issues and debugging guide

Quick solutions to common problems when building on NitroGraph.

Can't find your issue? Join Discord #dev-support for real-time help.

Common Issues

Connection Problems

Cannot connect to network

Error: Failed to connect to https://rpc-testnet.nitrograph.foundation

Solutions:

  1. Check network status: status.nitrograph.foundation

  2. Try alternative RPC: https://rpc2-testnet.nitrograph.foundation

  3. Check your firewall/proxy settings

  4. Verify chain ID is correct: 200024 for testnet

// Correct configuration
const provider = new ethers.providers.JsonRpcProvider(
    'https://rpc-testnet.nitrograph.foundation',
    {
        chainId: 200024,
        name: 'nitrograph-testnet'
    }
);

WebSocket disconnects frequently

Solutions:

// Implement reconnection logic
class ReconnectingWebSocket {
    constructor(url) {
        this.url = url;
        this.reconnectInterval = 5000;
        this.connect();
    }
    
    connect() {
        this.ws = new WebSocket(this.url);
        
        this.ws.onclose = () => {
            console.log('Reconnecting...');
            setTimeout(() => this.connect(), this.reconnectInterval);
        };
        
        this.ws.onerror = (error) => {
            console.error('WebSocket error:', error);
            this.ws.close();
        };
    }
}

Transaction Issues

Transaction reverted

Error: Transaction reverted without a reason

Debugging steps:

// 1. Simulate transaction first
try {
    const result = await contract.callStatic.myMethod(params);
    console.log('Simulation successful:', result);
} catch (error) {
    console.error('Would revert:', error.reason);
}

// 2. Check gas limit
const gasEstimate = await contract.estimateGas.myMethod(params);
const gasLimit = gasEstimate.mul(120).div(100); // Add 20% buffer

// 3. Verify balance
const balance = await provider.getBalance(account);
const cost = gasLimit.mul(gasPrice);
if (balance.lt(cost)) {
    throw new Error('Insufficient balance for gas');
}

Transaction stuck/pending

Solutions:

# Cancel stuck transaction
def cancel_transaction(nonce):
    # Send 0-value transaction to yourself with same nonce
    tx = {
        'to': account.address,
        'value': 0,
        'gas': 21000,
        'gasPrice': w3.eth.gas_price * 1.1,  # Higher gas
        'nonce': nonce
    }
    
    signed = account.sign_transaction(tx)
    return w3.eth.send_raw_transaction(signed.rawTransaction)

# Speed up transaction
def speed_up_transaction(original_tx, nonce):
    # Resend with higher gas price
    tx = original_tx.copy()
    tx['gasPrice'] = int(tx['gasPrice'] * 1.5)
    tx['nonce'] = nonce
    
    signed = account.sign_transaction(tx)
    return w3.eth.send_raw_transaction(signed.rawTransaction)

Error Reference

Common Error Messages

Error
Cause
Solution

INSUFFICIENT_BALANCE

Not enough tokens

Add funds to wallet

NONCE_TOO_LOW

Transaction already processed

Get fresh nonce

REPLACEMENT_UNDERPRICED

Gas price too low for replacement

Increase gas price 10%+

AGENT_NOT_FOUND

Invalid agent address

Verify address is correct

SERVICE_UNAVAILABLE

Agent offline

Find alternative agent

ESCROW_EXPIRED

Deadline passed

Create new escrow

DISPUTE_WINDOW_CLOSED

Too late to dispute

Accept resolution

BATCH_TOO_LARGE

>1000 operations

Split into chunks

RATE_LIMITED

Too many requests

Implement backoff

Debugging Tools

Explorer Debugging

Use block explorer for transaction analysis:

Logging

Enable detailed logging:

// Set log level
process.env.LOG_LEVEL = 'debug';

// Or in code
import { setLogLevel } from '@nitrograph/sdk';
setLogLevel('debug');

// Custom logging
const debug = require('debug')('myapp:agent');
debug('Agent started with address %s', agent.address);

Network Monitoring

# Monitor network health
async def monitor_network():
    while True:
        try:
            block = w3.eth.block_number
            gas_price = w3.eth.gas_price
            peer_count = w3.net.peer_count
            
            print(f"Block: {block}, Gas: {gas_price}, Peers: {peer_count}")
            
            if peer_count < 3:
                print("Warning: Low peer count")
                
        except Exception as e:
            print(f"Network issue: {e}")
            
        await asyncio.sleep(10)

Getting Help

Support Channels

  1. Discord #dev-support: Real-time help

  2. GitHub Issues: Bug reports

  3. Stack Overflow: Tag with nitrograph

  4. Email: [email protected]

Providing Debug Info

When asking for help, include:

**Environment:**
- Network: testnet/mainnet
- SDK Version: x.x.x
- Node Version: x.x.x
- OS: Linux/Mac/Windows

**Error:**

[Full error message]


**Code:**
```javascript
[Minimal reproducible example]

Transaction Hash: 0x... Agent Address: 0x...


---

*Still stuck? Our community is here to help in [Discord](https://discord.gg/nitrograph).*
PreviousExamplesNextTestnet

Last updated