Skip to main content

Troubleshooting

Common issues and their solutions.

Daemon Issues​

"Daemon is not running"​

Symptom: Commands show "Daemon IPC failed, using direct mode"

Solution:

runix daemon start
runix daemon status

If the daemon won't start, check:

runix doctor

"Address already in use" / Socket exists but daemon not running​

Symptom: runix daemon start fails, but the socket file exists

Solution: Remove the stale socket and PID file:

rm ~/.runix/runix.sock
rm ~/.runix/runix.pid
runix daemon start

Daemon crashes on startup​

Check the daemon logs:

# If running via systemd
journalctl --user -u runix

# If running in foreground for debugging
runix daemon run

Process Issues​

Process immediately exits with no output​

Possible causes:

  1. Wrong runtime — Check that runtime matches the entrypoint type
  2. Missing entrypoint — Verify the path exists and is executable
  3. Pre-start hook failure — Check hooks configuration
# Check the process status
runix status <name>

# View stderr
runix logs <name> --stderr

# Try running directly
runix start <name> --dry-run

Process keeps restarting (restart loop)​

Symptom: Process shows high restart count, never stays running

Diagnosis:

# Check exit code
runix status <name>

# View recent logs
runix logs <name> --lines 100

# Check if max_restarts is appropriate
runix inspect <name>

Solutions:

  • Fix the underlying application error
  • Increase backoff_base and backoff_max to slow the restart loop
  • Set restart_policy: never temporarily while debugging

"invalid transition: running → starting"​

This indicates a race condition where a restart was attempted while the process was already running. It should resolve on the next attempt. If it persists, file a bug.

Configuration Issues​

"config file not found"​

Runix looks for runix.yaml in the current directory. Specify the path explicitly:

runix start --config /path/to/runix.yaml

"duplicate process name"​

Process names must be unique within a namespace. Either:

  • Rename the duplicate process
  • Place them in different namespaces

"circular dependency detected"​

The depends_on chain has a cycle. Break the cycle by removing one dependency.

"invalid cron schedule"​

Cron expressions must follow 5-field or 6-field format:

# 5-field
*/5 * * * *      # Valid
0 */6 * * *      # Valid

# 6-field (with seconds)
0 */5 * * * *    # Valid

File Watching Issues​

Watch doesn't detect changes​

Possible causes:

  1. Path not watched — Check watch.paths includes the changed directory
  2. File is ignored — Check watch.ignore patterns
  3. Inotify limit reached (Linux) — Increase the limit: 
    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
    sudo sysctl -p

Watch triggers too many restarts​

Increase the debounce duration:

watch:
  debounce: 500ms  # Default: 100ms

Permission Issues​

"cannot write to ~/.runix/"​

Check directory permissions:

ls -la ~ | grep .runix
runix doctor  # Checks write permissions

Socket permission denied​

The socket at ~/.runix/runix.sock uses 0o660 permissions (owner + group). Ensure you're the owner or in the correct group.

Platform Issues​

Metrics show zero values (macOS/Windows)​

Per-process metrics reading from /proc only works on Linux. On other platforms, metrics return zero values. This is expected behavior.

Resource limits not enforced (macOS/Windows)​

cgroups v2 is Linux-only. Resource limits (cpu_quota, memory_limit) are not enforced on macOS or Windows.

Self-update fails​

Possible causes:

  1. No GitHub release for your platform
  2. Binary not writable — check permissions on the runix executable
  3. Network issues — verify connectivity to api.github.com
# Check for updates without installing
runix update --check

Log Issues​

"No logs available"​

Logs are stored per-app in ~/.runix/apps/<name>/:

ls ~/.runix/apps/
ls ~/.runix/apps/<name>/

If the directory doesn't exist, the process may have never started. Check status first.

Log files are very large​

Configure log rotation:

logging:
  max_size: 10485760   # 10MB
  max_files: 5
  max_age: 168h        # 7 days

Or manually flush logs:

runix flush <name>

Getting Help​

If none of these solutions work:

  1. Run runix doctor and include the output
  2. Check existing GitHub Issues
  3. Open a new issue with:
    • Runix version (runix version --verbose)
    • OS and architecture
    • Relevant config file (redact secrets)
    • Error messages and logs