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/diphyx/dxflow/main/assets/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 hub has --proxy enabled
  • 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 stat

Tips:

  • Enable streaming with ?stream=true for large data operations

High memory usage

# Monitor resource usage
dxflow stat

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 compose 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+R

File Operations

Upload/Download fails

# Check available disk space
df -h

# Test with smaller file first
dxflow fs upload small-file.txt /path/

Checklist:

  • Verify permissions on destination directory
  • Ensure sufficient disk space

ZIP operations fail

# Verify source exists
dxflow fs list /path
ZIP operations require 2x file size for temporary space

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 SystemLog Files
SystemD/tmp/dxflow.out and /tmp/dxflow.err
OpenRC/var/log/dxflow-engine.out and .err

Common Error Codes

ErrorMeaningFix
bind: address already in usePort conflictChange port or kill process
401 UnauthorizedToken expiredRun dxflow ping
connection refusedEngine not runningRun dxflow boot up
permission deniedFile permissionsCheck ownership/permissions
Need More Help? Report issues at GitHub with diagnostic info from dxflow engine info