Server Path
Lesson 8 of 8
15 min

Debugging Server Issues

Learning Objectives

  • Inspect PAYMENT-REQUIRED and PAYMENT-RESPONSE headers
  • Identify common verification errors
  • Diagnose settlement failures
  • Use lifecycle hooks for debugging
  • Troubleshoot facilitator connection issues

Common Server Issues

When building x402 servers, you may encounter:

Configuration Issues:

•Wrong network identifiers
•Invalid wallet addresses
•Facilitator connection failures

Verification Issues:

•Invalid payment signatures
•Mismatched payment requirements
•Network mismatch errors

Settlement Issues:

•Insufficient funds in payer's wallet
•Transaction failures on-chain
•Timeout errors

Debugging Tool 1: Inspecting Headers

The PAYMENT-REQUIRED header tells clients what payment is needed. Decode it to debug:

bash
# Make a request without payment
curl -i http://localhost:4021/weather

# Response:
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIi...

# Decode the header
echo "eyJ4NDAyVmVyc2lvbiI6MiwiZXJyb3IiOiJQYXltZW50IHJlcXVpcmVkIi..." | base64 -d | jq
json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "http://localhost:4021/weather",
    "description": "Weather data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300
    }
  ]
}
Check that network, amount, and payTo are correct. The amount is in atomic units (1000 = 0.001 USDC for 6 decimal tokens).

Common Error 1: Wrong Network Identifier

Error: Unsupported network: eip155:1

Cause: You configured a network that isn't registered with your resource server.

Solution: Make sure you registered the scheme for that network:

typescript
// ❌ Wrong - network not registered
const server = new x402ResourceServer(facilitatorClient);
// Only EVM scheme registered for Base Sepolia by default

// ✅ Correct - explicitly register networks
const server = new x402ResourceServer(facilitatorClient);
registerExactEvmScheme(server);  // Registers all EVM networks
// OR
server.register('eip155:84532', new ExactEvmScheme());  // Specific network

Common Error 2: Invalid Payment Signature

Error: Payment verification failed: Invalid signature

Cause: The payment signature doesn't match the requirements or is malformed.

Solution: Check that client and server requirements match:

typescript
// Add onBeforeVerify hook to inspect requirements
const server = new x402ResourceServer(facilitatorClient)
  .register('eip155:84532', new ExactEvmScheme())
  .onBeforeVerify(async (context) => {
    console.log('Verifying payment:');
    console.log('- Network:', context.requirements.network);
    console.log('- Amount:', context.requirements.amount);
    console.log('- PayTo:', context.requirements.payTo);
    console.log('- Signature from:', context.signature.from);
    return undefined;
  });

Common Error 3: Settlement Timeout

Error: Settlement timed out after 300 seconds

Cause: The on-chain transaction took too long or failed.

Solution: Check facilitator status and network congestion:

typescript
// Add settlement hooks to monitor progress
const server = new x402ResourceServer(facilitatorClient)
  .register('eip155:84532', new ExactEvmScheme())
  .onBeforeSettle(async (context) => {
    console.log('Starting settlement...');
    return undefined;
  })
  .onAfterSettle(async (context) => {
    console.log('✅ Settlement succeeded:', context.result.transaction);
    return undefined;
  })
  .onSettleFailure(async (context) => {
    console.error('❌ Settlement failed:', context.error.message);
    // Check error type
    if (context.error.message.includes('timeout')) {
      console.error('Network congestion or facilitator issue');
    }
    return undefined;
  });

Common Error 4: Facilitator Connection Failed

Error: Failed to connect to facilitator

Cause: Wrong facilitator URL or facilitator is down.

Solution:

typescript
// Test facilitator connection
const facilitatorClient = new HTTPFacilitatorClient({
  url: 'https://api.cdp.coinbase.com/platform/v2/x402'
});

// Add error handling
try {
  const server = new x402ResourceServer(facilitatorClient);
  console.log('✅ Facilitator connected');
} catch (error) {
  console.error('❌ Facilitator connection failed:', error);
  // Check URL, network connectivity
}
For testnet, use https://x402.org/facilitator. For mainnet, use https://api.cdp.coinbase.com/platform/v2/x402.

Debugging Checklist

When things go wrong:

1.✅ Check PAYMENT-REQUIRED header structure
2.✅ Verify network identifiers match (CAIP-2 format)
3.✅ Confirm wallet addresses are correct format
4.✅ Test facilitator connection
5.✅ Add lifecycle hooks for detailed logs
6.✅ Check amount is in atomic units (multiply by 10^decimals)
7.✅ Verify schemes are registered for all networks
8.✅ Test with small amounts first

Debug a Broken Server

Fix common configuration errors in an x402 server

Requirements:

Correct facilitator URL

Facilitator URL is correct

Scheme registered

EVM scheme is registered

Valid EVM address

PayTo address is valid EVM format

Your Solution
Previous
Dynamic Pricing Strategies
Complete Course