FAQs
Troubleshooting
Common dxflow symptoms and their fixes
Start with these three commands — between them they answer most questions:
dxflow engine info # identity, paths, hardware, and which runtimes were detected
dxflow healthcheck # detailed engine health
dxflow stats # live CPU, memory, disk, and network
engine info spawns a temporary engine when none is running, so it works even before the first boot. healthcheck and stats need a running engine.
Installation
| Symptom | Fix |
|---|---|
dxflow: command not found | Confirm the install directory is on your PATH, then open a new terminal. See Installation. |
permission denied running dxflow | sudo chmod +x /usr/local/bin/dxflow |
| macOS blocks the binary | The releases are unsigned. System Settings → Privacy & Security → Open Anyway. |
Boot
| Symptom | Fix |
|---|---|
bind: address already in use | Another process holds the port. Find it with sudo lsof -i :80, or move dxflow with dxflow config set http-port 8080. |
permission denied binding a port | Ports below 1024 are privileged. See Port Binding. |
| Daemon won't start | --daemon needs Linux with SystemD or OpenRC. See Persistent Daemon. |
| Daemon stops at logout | Enable lingering: sudo loginctl enable-linger $USER. |
| Engine exits on a license error | The license file is corrupt or belongs to another engine. dxflow license deactivate reverts to the built-in one. |
Connecting
| Symptom | Fix |
|---|---|
connection refused | The engine isn't running, or it's listening on a Unix socket only. Boot it with --http or --console. |
401 Unauthorized | The token expired. dxflow config unset connection-token && dxflow engine ping re-authenticates. |
| Console shows the sign-in dialog | Expected — every HTTP connection authenticates. Sign in with a private key or a code from dxflow engine pair. See Authentication. |
| Console unreachable from another machine | Check the firewall allows the port, and that the engine is bound to 0.0.0.0 rather than loopback. |
| API responds but the console won't render | Hard-refresh the browser (Ctrl / Cmd + Shift + R). |
Workflows
| Symptom | Fix |
|---|---|
name required on create | A definition needs a top-level name and a steps list. See the workflow schema. |
invalid identity … | The identity is folded to letters and digits first, and the result must open with two letters — 2024-run folds to 2024run. See Identities. |
workflow already exists for a name you never used | Folding is not reversible: open-ui and Open UI both name openui, and anything past 12 characters is cut, so data-pipeline-2024 and -2025 collide. |
step[N]: image required | Every step needs an image. |
mode 'sequential' requires a command | Sequential steps need a command. Use mode: parallel for a service that runs its image's own entrypoint. |
| A step exits immediately | Read the logs: dxflow workflow logs <identity>. Add --live to follow a running one. |
| No containers start | Check a runtime was detected in dxflow engine info, and that its daemon is running. |
| Port already mapped | Another workflow holds the host port. Move it for one run: dxflow workflow start <identity> --override port.<step>.<port-name>=9090. |
Artifacts
| Symptom | Fix |
|---|---|
| Upload or download fails | Check free space with df -h and that the destination directory exists (dxflow artifact list <path>). |
| Zip fails on a large directory | Archiving needs temporary space roughly equal to the source size. |
Logs
| Where | Path |
|---|---|
| Daemon stdout / stderr | /tmp/dxflow.out and /tmp/dxflow.err (SystemD and OpenRC alike) |
| SystemD journal | journalctl --user -u dxflow -f |
| Workflow step output | dxflow workflow logs <identity>, or step-{index}.out / .err under the workflow directory |
Run the engine at debug level to see configuration resolution, runtime command construction, and request handling:
dxflow --log-level=debug boot up --console
Still stuck? Report it at GitHub with the output of
dxflow engine info.