FAQs
Troubleshooting
Common issues and solutions for dxflow engine deployment and operations
Installation
Command not found
# Add to PATH
export PATH="/usr/local/bin:$PATH"
# Or reinstall
wget -qO- https://raw.githubusercontent.com/dxflow-ai/community/main/install.sh | sudo bash
Permission denied
# Linux/macOS
chmod +x /usr/local/bin/dxflow
Alternatively on macOS: System Settings → Privacy & Security → Open Anyway
Boot issues
Port already in use
# Find process using the port
sudo lsof -i :80
# Kill the process
sudo kill -9 <PID>
# Or change dxflow port
dxflow config set http-port 8080
Daemon won't start
Linux-only feature. See Persistent Daemon FAQ
Cannot use --proxy and --bridge together
These modes are mutually exclusive. See Tunneling docs
Network
Bridge won't connect to hub
# Test bridge connection
dxflow bridge list
Checklist:
- Verify
bridge-gatewaypoints at your own hub (dxflow config get bridge-gateway) - Verify hub has
--proxyenabled - Check firewall allows port 80/443
Subdomain not accessible
# Test bridge connection
dxflow bridge list
Checklist:
- Check DNS wildcard:
*.domain.com → hub-ip - Verify proxy is running
Authentication
401 Unauthorized - JWT token expired
# Regenerate token manually
dxflow engine token
# Or auto-regenerate
dxflow ping
RSA key authentication fails
# Verify RSA format
openssl rsa -in key.pem -check
# Generate new key
dxflow key generate mykey
# Register public key
dxflow key register mykey.pub
Performance
Slow API responses
# Check health status
dxflow healthcheck
# View resource statistics
dxflow stats
Tips:
- Enable streaming with
?stream=truefor large data operations
High memory usage
# Monitor resource usage
dxflow stats
Tips:
- Use streaming for large operations
- Limit concurrent workflows
Bridge tunnel has high latency
This is expected behavior. Use proxy mode for production environments.
Workflows
Docker containers won't start
# Verify Docker is running
docker ps
# Check container logs
dxflow workflow logs <name>
# Validate compose file
docker-compose -f file.yml config
Web interface not loading
# Check engine status
dxflow ping
# Test API directly
curl http://localhost/api/engine/ping
If API works but UI doesn't load, clear browser cache with
Ctrl+Shift+RFile operations
Upload/Download fails
# Check available disk space
df -h
# Test with smaller file first
dxflow artifact upload small-file.txt /path/
Checklist:
- Verify permissions on destination directory
- Ensure sufficient disk space
ZIP operations fail
# Verify source exists
dxflow artifact list /path
ZIP operations require 2x file size for temporary space
Quick reference
Debug commands
dxflow engine info # System details
dxflow stats # Resource usage
dxflow healthcheck # Health status
dxflow --log-level=debug boot up --console # Debug mode
Log locations (daemon)
| Init System | Log Files |
|---|---|
| SystemD | /tmp/dxflow.out and /tmp/dxflow.err |
| OpenRC | /tmp/dxflow.out and /tmp/dxflow.err |
Common error codes
| Error | Meaning | Fix |
|---|---|---|
bind: address already in use | Port conflict | Change port or kill process |
401 Unauthorized | Token expired | Run dxflow ping |
connection refused | Engine not running | Run dxflow boot up --console |
permission denied | File permissions | Check ownership/permissions |
Need More Help? Report issues at GitHub with diagnostic info from
dxflow engine info