Overview

This section helps you diagnose and resolve common issues with NCN Network v2.

---

Quick Diagnostics

Health Check Commands

# Check Gateway
curl http://localhost:8080/health

# Check P2P Registry (if health endpoint available)
grpcurl -plaintext localhost:50050 grpc.health.v1.Health/Check

# Check process status
ps aux | grep -E "(gateway|compute|registry)"

# Check port bindings
netstat -tlnp | grep -E "(50050|50051|8080|9000|8828)"

Log Locations

Component	Log Location
Gateway	stdout/stderr or ./logs/gateway.log
Compute	stdout/stderr or ./logs/compute.log
Registry	stdout/stderr or ./logs/registry.log

Enable Debug Logging

# Full debug
export RUST_LOG=debug

# Component-specific
export RUST_LOG=gateway_node=debug,compute_node=info

# Trace specific module
export RUST_LOG=gateway_node::payment=trace

---

Troubleshooting Guides

Common Issues

General issues affecting all components:

• Build failures

• Configuration errors

• Network connectivity

Gateway Issues

Gateway-specific problems:

• Connection failures

• Payment processing

• Compute node management

Compute Issues

Compute node problems:

• Sandbox failures

• Model loading

• Execution timeouts

Payment Issues

Blockchain and payment problems:

• Transaction failures

• Confirmation delays

• Refund issues

FAQ

Frequently asked questions

---

Common Issues Quick Reference

Build Failures

Error	Cause	Solution
linker not found	Missing build tools	Install build-essential
protoc not found	Missing protoc	Install protobuf-compiler
cannot find -lssl	Missing OpenSSL	Install libssl-dev

Connection Failures

Error	Cause	Solution
Connection refused	Service not running	Start the service
DNS resolution failed	Wrong hostname	Check service address
TLS handshake failed	Certificate issue	Verify TLS config

Execution Failures

Error	Cause	Solution
Timeout exceeded	Slow execution	Increase timeout
Out of memory	Model too large	Increase memory limit
Permission denied	Sandbox restriction	Check sandbox config

---

Error Messages

Gateway Errors

Error: No compute nodes available for model X

Cause: No compute node supports the requested model Solution:

• Verify compute nodes are connected

• Check model is in subnet

• Verify compute node's --model-path

Error: Payment verification failed: Transaction not found

Cause: Blockchain transaction not visible Solution:

• Wait for more confirmations

• Verify RPC URL is correct

• Check transaction hash

Compute Node Errors

Error: Sandbox execution failed: seccomp violation

Cause: Model attempted blocked syscall Solution:

• Check model compatibility

• Use SANDBOX_MODE=permissive for debugging

• Review seccomp filter

Error: Model not found at path X

Cause: Model file missing Solution:

• Verify --model-path is correct

• Enable --sync-models for auto-download

• Check file permissions

Registry Errors

Error: Insufficient validators for consensus

Cause: Not enough validators available Solution:

• Register more validators

• Check validator connectivity

• Reduce MIN_VALIDATORS_FOR_CONSENSUS

---

Diagnostic Tools

Network Diagnostics

# Test gRPC connectivity
grpcurl -plaintext localhost:50051 list

# Test HTTP endpoint
curl -v http://localhost:8080/api/v1/health

# Check P2P peers
# (If diagnostic endpoint available)

Process Diagnostics

# Check memory usage
ps -o pid,rss,command -p $(pgrep gateway_node)

# Check open files
lsof -p $(pgrep gateway_node) | head -20

# Check network connections
ss -tlnp | grep gateway

Blockchain Diagnostics

# Check RPC connectivity
curl -X POST $RPC_URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Check contract
cast call $CONTRACT_ADDRESS "minValidatorSignatures()" --rpc-url $RPC_URL

---

Recovery Procedures

Gateway Recovery

1. Stop gateway: pkill gateway_node

2. Check state file: ls -la ./data/gateway_state.json

3. Backup if needed: cp ./data/gateway_state.json ./data/gateway_state.json.bak

4. Restart: cargo run --bin gateway_node

Compute Node Recovery

1. Stop compute node: pkill compute_node

2. Clear model cache: rm -rf ./cache/*

3. Verify models: ls -la ./models/

4. Restart: cargo run --bin compute_node -- --gateway-addr http://localhost:50051

Registry Recovery

1. Stop registry: pkill p2p_registry

2. Check DHT data: ls -la ./data/dht/

3. Clear if corrupted: rm -rf ./data/dht/*

4. Restart: cargo run --bin p2p_registry_node

---

Getting Help

Information to Provide

When reporting issues, include:

1. Component and version: cargo run --bin gateway_node -- --version

2. OS and architecture: uname -a

3. Full error message: Copy complete error

4. Logs: Relevant log excerpts

5. Configuration: Sanitized config (no private keys!)

6. Steps to reproduce: How to trigger the issue

Support Channels

• GitHub Issues: Bug reports and feature requests

• Documentation: This troubleshooting guide

• Community: [Discord/Telegram link if available]

---

Debug Mode

Enable Debug Mode

# Maximum debug output
export RUST_LOG=trace
export RUST_BACKTRACE=1

# Run with debug mode
cargo run --bin gateway_node

Debug Specific Issues

# Debug sandbox only
export RUST_LOG=compute_node::sandbox=trace

# Debug payment only
export RUST_LOG=gateway_node::payment=trace

# Debug P2P networking
export RUST_LOG=libp2p=debug,p2p_registry_node=trace

Performance Profiling

# Enable profiling
cargo build --release --features profiling

# Run with profiler
perf record -g ./target/release/gateway_node
perf report

---

Next Steps

• Common Issues - Detailed solutions

• Gateway Issues - Gateway-specific help

• Compute Issues - Compute node help

• FAQ - Frequently asked questions