FAQs
Troubleshooting
Common issues and solutions for dxflow engine deployment and operations
Installation
Solution:
- Add
/usr/local/binto PATH - Reinstall:
wget -qO- https://raw.githubusercontent.com/diphyx/dxflow/main/assets/install.sh | sudo bash
Solution:
- Linux/macOS:
chmod +x /usr/local/bin/dxflow - macOS: System Settings → Privacy & Security → Open Anyway
Boot Issues
Solution:
- Find process:
sudo lsof -i :80 - Kill process:
sudo kill -9 <PID> - Or change port:
dxflow config set http-port 8080
Solution: Linux-only feature. See Persistent Daemon FAQ
Solution: These are mutually exclusive. See Tunneling docs
Network
Solution:
- Verify hub has
--proxyenabled - Check firewall allows port 80/443
- Test:
dxflow bridge list
Solution:
- Check DNS wildcard:
*.domain.com → hub-ip - Verify proxy is running
- Test bridge connection:
dxflow bridge list
Authentication
Solution:
- Regenerate:
dxflow engine token - Or auto-regenerate:
dxflow ping
Solution:
- Verify RSA format:
openssl rsa -in key.pem -check - Generate new:
dxflow key generate mykey - Register:
dxflow key register mykey.pub
Performance
Solution:
- Enable streaming:
?stream=truefor large data - Check health:
dxflow healthcheck - View stats:
dxflow stat
Solution:
- Use streaming for large operations
- Limit concurrent workflows
- Monitor:
dxflow stat
Note: This is expected behavior. Use proxy mode for production environments.
Workflows
Solution:
- Verify Docker running:
docker ps - Check logs:
dxflow compose logs <name> - Validate compose:
docker-compose -f file.yml config
Solution:
- Check engine:
dxflow ping - Test API:
curl http://localhost/api/engine/ping - Clear browser cache:
Ctrl+Shift+R
File Operations
Solution:
- Check disk space:
df -h - Verify permissions on destination
- Try smaller file first
Solution:
- Requires 2x file size for temporary space
- Check source exists:
dxflow fs list /path
Quick Reference
Debug Commands
dxflow engine info # System details
dxflow stat # Resource usage
dxflow healthcheck # Health status
dxflow --log-level=debug boot up # Debug mode
Log Locations (Daemon)
| Init System | Log Files |
|---|---|
| SystemD | /tmp/dxflow.out and /tmp/dxflow.err |
| OpenRC | /var/log/dxflow-engine.out and .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 |
permission denied | File permissions | Check ownership/permissions |
Need More Help? Report issues at GitHub with diagnostic info from
dxflow engine info