Troubleshooting Guide

Connection Issues

WebSocket Connection Failed

Symptoms:

"Connection refused" error
WebSocket timeout
Cannot connect to ws://localhost:8081

Solutions:

Check if daemon is running:

# Check process
ps aux | grep lxd

# Check port
lsof -i :8081

Start the daemon:

lxd start --config /path/to/config.yaml

Check firewall:

# macOS
sudo pfctl -sr | grep 8081

# Linux
sudo iptables -L -n | grep 8081

Verify endpoint:

# Test WebSocket
wscat -c ws://localhost:8081

# Test REST
curl http://localhost:8080/health

SSL/TLS Certificate Errors

Symptoms:

"Certificate verify failed"
"Unable to verify the first certificate"

Solutions:

# Update CA certificates
# macOS
brew install ca-certificates

# Linux
sudo apt update && sudo apt install ca-certificates

# Or disable verification (development only!)
export NODE_TLS_REJECT_UNAUTHORIZED=0

Connection Drops

Symptoms:

Frequent disconnections
"Connection reset by peer"

Solutions:

Implement reconnection logic:

const connect = () => {
  const ws = new WebSocket(url);
  ws.onclose = () => setTimeout(connect, 1000);
};

Send heartbeats:

setInterval(() => ws.send('{"type":"ping"}'), 30000);

Check network stability:

ping -c 100 dex.lux.network

Order Issues

Order Rejected

Error: "Insufficient balance"

{"error": "insufficient_balance", "required": "1000.00", "available": "500.00"}

Solution: Ensure account has sufficient funds including fees.

Error: "Price out of bounds"

{"error": "price_out_of_bounds", "min": "0.01", "max": "1000000.00"}

Solution: Adjust price within allowed range.

Error: "Size below minimum"

{"error": "size_below_minimum", "minimum": "0.001", "provided": "0.0001"}

Solution: Increase order size to meet minimum.

Error: "Self-trade prevented"

{"error": "self_trade_prevented"}

Solution: Your order would match against your own. Adjust price or cancel existing order.

Order Not Filling

Possible causes:

Limit price too aggressive:
- Buy orders: price too low
- Sell orders: price too high
Insufficient liquidity:

# Check order book depth
lx-cli orderbook BTC-USD --depth 20

Post-only rejection:
- Post-only orders rejected if they would take liquidity

Order Stuck in Pending

Solutions:

Check order status:

lx-cli orders --status pending

Cancel and retry:

lx-cli cancel --order-id ord_123

Check network status:

lx-cli status

API Issues

Authentication Failures

Error: "Invalid signature"

Common causes:

Timestamp drift:

// Ensure system time is synchronized
const timestamp = Date.now();
// Timestamp must be within 30 seconds

Wrong signing format:

// Correct format
const message = `${timestamp}${method}${path}${body}`;
const signature = hmacSHA256(secret, message);

Encoding issues:

// Ensure UTF-8 encoding
const body = JSON.stringify(data);  // Not toString()

Error: "API key not found"

Solutions:

Verify key is correct (case-sensitive)
Check key hasn't been revoked
Ensure key has required permissions

Rate Limiting

Error: "Rate limit exceeded"

{"error": "rate_limit_exceeded", "retry_after": 1000}

Solutions:

Implement backoff:

const backoff = async (attempt: number) => {
  const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
  await sleep(delay);
};

Batch requests:

// Instead of multiple single orders
const orders = [order1, order2, order3];
ws.send(JSON.stringify({ type: "batch_orders", data: orders }));

Use WebSocket for real-time data:

// Subscribe once instead of polling
ws.send(JSON.stringify({ type: "subscribe", channel: "orderbook", symbol: "BTC-USD" }));

Timeout Errors

Error: "Request timeout"

Solutions:

Increase timeout:

const response = await fetch(url, { timeout: 30000 });

Check server health:

curl -w "@curl-format.txt" https://api.lux.exchange/health

Use primary endpoint:

Global (GeoDNS): api.lux.exchange
Kansas City DC: Direct colocation available

Balance Issues

Balance Not Updating

Possible causes:

Pending settlement:
- Wait 1-2 blocks (~1-2 seconds)
Funds in open orders:

# Check reserved balance
lx-cli balances --show-reserved

Cache issues:

# Force refresh
lx-cli balances --no-cache

Incorrect Balance Shown

Solutions:

Reconcile with blockchain:

lx-cli reconcile --account 0x...

Check all positions:

lx-cli positions --all

Verify deposits:

lx-cli deposits --status pending

SDK Issues

Installation Failures

Python:

# Use virtual environment
python -m venv venv
source venv/bin/activate
pip install lux-dex

TypeScript:

# Clear npm cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Rust:

# Update toolchain
rustup update
cargo clean
cargo build

Go:

# Clear module cache
go clean -modcache
go mod download

Build Errors

C++ missing dependencies:

# macOS
brew install cmake nlohmann-json websocketpp asio

# Linux
sudo apt install cmake nlohmann-json3-dev libwebsocketpp-dev libasio-dev

C missing libwebsockets:

# macOS
brew install libwebsockets

# Linux
sudo apt install libwebsockets-dev

Performance Issues

High Latency

Diagnosis:

# Measure round-trip time
lx-cli ping --count 100

# Check network path
traceroute dex.lux.network

Solutions:

Use colocated servers:
- AWS us-east-1 for US
- AWS eu-west-1 for EU
Enable compression:

const ws = new WebSocket(url, { perMessageDeflate: true });

Use binary protocol:

ws.binaryType = 'arraybuffer';

Memory Leaks

Symptoms:

Increasing memory usage over time
Out of memory errors

Solutions:

Clean up subscriptions:

ws.send(JSON.stringify({ type: "unsubscribe", channel: "orderbook" }));

Limit order book depth:

// Only subscribe to top 10 levels
{ type: "subscribe", channel: "orderbook", depth: 10 }

Use streaming instead of snapshots:

// Incremental updates instead of full snapshots
{ type: "subscribe", channel: "orderbook_delta" }

Still Need Help?

If you've tried the above solutions and still have issues:

Gather diagnostic info:

lx-cli diagnostics > diagnostics.txt

Open GitHub issue with:
- Error messages
- Steps to reproduce
- Diagnostic output
- SDK/client version
Join Discord for real-time community help

Troubleshooting

On this page