Skip to main content

Troubleshooting

Solutions to common issues when getting started with Expanso.

Node Issues​

Node Not Connecting?​

Symptoms: Node doesn't appear in Expanso Cloud after bootstrap.

Solutions:

  • Verify the bootstrap token is correct
  • Check network connectivity to cloud.expanso.io
  • Review edge agent logs: expanso-edge logs
  • Ensure firewall allows outbound HTTPS connections
  • Check system time is synchronized (required for authentication)

Still not working?

# Check agent status
expanso-edge status

# View detailed logs
expanso-edge logs --level debug

# Verify network connectivity
curl -v https://cloud.expanso.io/health

Pipeline Issues​

Pipeline Not Deploying?​

Symptoms: Pipeline shows "Pending" or fails to deploy.

Solutions:

  • Ensure the node is online (green status in UI)
  • Check for configuration errors in the pipeline YAML
  • Review deployment logs in the Expanso Cloud UI
  • Verify node has sufficient resources (CPU, memory)

Debugging steps:

  1. Check node status in the UI
  2. View deployment logs for error messages
  3. Validate pipeline configuration syntax
  4. Check node agent logs for deployment errors

No Data Flowing?​

Symptoms: Pipeline deployed but no data appears in outputs.

Solutions:

  • Verify the input source has data available
  • Check file paths and permissions for file inputs
  • Review processor logic - filters may be dropping messages
  • Check edge agent logs for errors

Debugging steps:

# View agent logs
expanso-edge logs

# Check for specific pipeline errors
expanso-edge logs | grep "pipeline-name"

# Verify input source
# For file inputs:
ls -la /path/to/input/files

# For network inputs:
netstat -an | grep PORT

Pipeline Readiness Timeout?​

Symptoms: Pipeline deployment fails with "Pipeline failed to become ready within X" error.

Solutions:

  • Check the error message—it includes the last specific error that occurred during startup
  • Verify input sources are accessible (database running, file paths exist)
  • Check for port conflicts if using HTTP server inputs
  • Review connection settings for typos (credentials, URLs)
  • Check network connectivity to external services
  • Review edge agent logs for more details

Debugging steps:

# Check edge agent logs for detailed errors
expanso-edge logs --level debug

# Verify network connectivity to input sources
curl -v http://your-input-source:port

# Check for port conflicts
netstat -an | grep PORT

Installation Issues​

Permission Denied During Install​

Solution: Run install script with appropriate permissions:

# Linux/macOS
curl -fsSL https://get.expanso.io/edge/install.sh | sudo bash

# Or install to user directory (no sudo)
curl -fsSL https://get.expanso.io/edge/install.sh | PREFIX=$HOME/.local bash

Bootstrap Token Expired​

Symptoms: "Invalid token" or "Token expired" error.

Solution: Bootstrap tokens expire after 24 hours. Generate a new token:

  1. Go to your network in Expanso Cloud
  2. Click Add Agent
  3. Copy the new bootstrap token
  4. Run bootstrap command again with new token

Performance Issues​

High CPU Usage​

Causes:

  • High message throughput
  • Complex processors (regex, parsing)
  • Insufficient batching

Solutions:

  • Increase batch sizes in processors
  • Use simpler processing logic where possible
  • Add more nodes to distribute load
  • Monitor metrics to identify bottlenecks

High Memory Usage​

Causes:

  • Large message sizes
  • Buffer accumulation
  • Memory leaks in custom processors

Solutions:

  • Monitor buffer metrics in UI
  • Adjust buffer sizes in pipeline config
  • Restart agent if memory grows unbounded
  • Check for data accumulation in processors

Network Issues​

Connection Timeouts​

Symptoms: Agent can't reach cloud.expanso.io.

Solutions:

  • Verify outbound HTTPS (port 443) is allowed
  • Check proxy settings if behind corporate firewall
  • Ensure DNS resolution works for cloud.expanso.io
  • Test connectivity: curl https://cloud.expanso.io/health

TLS/SSL Errors​

Symptoms: Certificate verification errors.

Solutions:

  • Ensure system time is correct
  • Update system CA certificates
  • Check for corporate SSL inspection/MITM
  • Verify no proxy is intercepting HTTPS traffic

Network Diagnostics​

Use the --verbose flag to get detailed network diagnostics and pinpoint where connectivity is failing.

# During bootstrap
expanso-edge bootstrap --token YOUR_TOKEN --verbose

# During run
expanso-edge run --verbose

What verbose mode checks:

  • Resolver: DNS configuration file in use
  • DNS Servers: Configured nameservers
  • Proxy: Whether an HTTP proxy is detected
  • DNS: Hostname resolution status
  • TCP: TCP connection to server
  • TLS: TLS handshake completion

Example output:

Diagnostics:
- Resolver: /etc/resolv.conf
- DNS Servers: 8.8.8.8, 8.8.4.4
- Proxy: none
- DNS: ok (192.0.2.1)
- TCP: ok (192.0.2.1:443 in 45ms)
- TLS: ok (TLS1.3)

Common diagnostic failures:

DiagnosticFailureLikely Cause
DNSfailed (no such host)DNS resolution issue - check nameservers
TCPfailed (connection refused)Firewall blocking outbound connections
TCPfailed (timeout)Network unreachable or blocked
TLSfailed (certificate verify failed)Corporate proxy intercepting HTTPS
Proxyusing http://proxy:8080Traffic routed through proxy - may need --no-proxy

Getting More Help​

Log Collection​

When reporting issues, include:

# Agent version
expanso-edge version

# System info
uname -a

# Recent logs
expanso-edge logs --tail 100

# Node status
expanso-edge status

Support Channels​

Known Issues​

Check GitHub issues for known problems and workarounds: