Skip to main content

Troubleshooting

This page covers common issues and their solutions.

Common Issues​

1. Node Not Appearing in Available Nodes​

Problem: Your node doesn't appear in the /info endpoint response.

Solutions:

  • Ensure you're calling registerNode() in your flow file
  • Check that your flow file is exported in flows/index.ts
  • Verify your node is exported in the main index.ts
  • Check for TypeScript compilation errors
  • Restart the server after adding your node

2. Sync State Failures​

Problem: syncState() returns an error.

Solutions:

  • Check API endpoint URLs and authentication
  • Verify network connectivity
  • Handle API rate limiting
  • Implement proper error handling and fallbacks
  • Check if the API response format matches expectations
  • Verify API keys are set correctly in environment variables

3. Swap Validation Issues​

Problem: Valid swaps are being rejected by isSwapEnabled().

Solutions:

  • Check token address normalization (case sensitivity, format)
  • Verify chain ID mapping (numeric vs. string, aliases)
  • Ensure token data is properly synced
  • Add debug logging to validation logic
  • Check if tokens are in the supportedTokens list
  • Verify token addresses match exactly (including checksum)

4. API Integration Problems​

Problem: External API calls are failing.

Solutions:

  • Verify API credentials and endpoints
  • Check request format and headers
  • Implement proper retry logic
  • Handle different response formats
  • Check for rate limiting
  • Verify timeout settings
  • Test API calls independently (e.g., with curl or Postman)

5. Same-chain vs Cross-chain Behavior Differences​

Problem: Different behavior for same-chain vs cross-chain swaps.

Solutions:

  • Meson: Supports both same-chain and cross-chain; failing same-chain tests often stem from amount formatting. Ensure you pass decimal strings, not atomic units
  • GasZip: Supports only native-to-native flows and validates per-chain limits; failures usually indicate inbound/outbound capacity or amount bounds
  • NEAR: Requires correct asset ID resolution; failures often arise from passing raw contract addresses without mapping to nep141:/nep245:

Debugging Tips​

1. Enable Debug Logging​

// Add debug logging to key methods
console.log(`[${this.id}] Processing request:`, input);
console.log(`[${this.id}] Supported tokens:`, this.supportedTokens.length);
console.log(`[${this.id}] API response:`, JSON.stringify(data, null, 2));

2. Test Individual Components​

// Test sync state separately
const syncResult = await node.syncState();
console.log('Sync result:', syncResult);

// Test token validation separately
const isValid = node.isSwapEnabled(inputToken, outputToken);
console.log('Swap enabled:', isValid);

// Test with minimal request
const minimalRequest = {
  input_token: { chain_id: '1', address: '0x...', decimals: 18 },
  output_token: { chain_id: '137', address: '0x...', decimals: 6 },
  amount_in: '1000000',
  // ... other required fields
};
const result = await node.processRequest(minimalRequest);
console.log('Process result:', result);

3. Validate Data Formats​

// Check if your data matches expected formats
console.log('Token format:', JSON.stringify(token, null, 2));
console.log('Request format:', JSON.stringify(request, null, 2));
console.log('Response format:', JSON.stringify(response, null, 2));

4. Monitor API Responses​

// Log API responses for debugging
const response = await fetch(url);
const data = await response.json();
console.log('API Response:', JSON.stringify(data, null, 2));
console.log('Response status:', response.status);
console.log('Response headers:', response.headers);

5. Leverage Existing Tests​

Review and run existing tests for reference:

  • NEAR: ts/src/nodes/near/test-end-to-end-comprehensive.test.ts, test-same-chain-swaps.test.ts
  • Meson: ts/src/nodes/meson/test-end-to-end-comprehensive.test.ts
  • GasZip: ts/src/nodes/gaszip/test_all_chains.test.ts
  • Mayan: End-to-end examples in ts/src/nodes/mayan/flows/*

Common Error Messages​

"Node not found"​

  • Cause: Node not registered or ID mismatch
  • Solution: Check registration in flow file and main index

"Swap not supported"​

  • Cause: Token pair not in supported tokens or validation failed
  • Solution: Check isSwapEnabled() logic and token data

"Network error"​

  • Cause: API call failed or timeout
  • Solution: Check network connectivity, API endpoint, and timeout settings

"Invalid amount"​

  • Cause: Amount format incorrect or out of bounds
  • Solution: Verify amount format (string with decimals) and check limits

"State sync failed"​

  • Cause: Failed to fetch or parse state data
  • Solution: Check API endpoint, authentication, and response format

Getting Help​

If you encounter issues not covered in this guide:

  1. Check existing node implementations for reference (NEAR, Meson, GasZip, Mayan)
  2. Review error logs for specific error messages
  3. Test with minimal implementations first
  4. Use the debugging tips above
  5. Check the main repository for updates and examples
  6. Review the code structure to understand the system better

Next Steps​