Troubleshooting

Troubleshooting

Quick solutions to common DevAll issues.

Service Issues

Service stuck on “starting”

Your service output doesn’t match DevAll’s detection patterns.

Solution: Check if your service outputs “Server running”, “Listening on”, or a localhost URL. DevAll uses these patterns to detect the running state.

# If your service uses different output, it may stay in "starting" state
# After 2 seconds with output, DevAll assumes it's running anyway

Port already in use

Another process is using the port your service needs.

Solution: Enable stealPort in your service config:

services:
  - name: API
    port: 3000
    stealPort: true  # Kills any process on port 3000 before starting

Service crashes immediately

Check for missing dependencies or incorrect working directory.

Solution: View the error logs in the terminal, then:

# For Node.js projects with missing modules
npm install

# Or enable auto-install
services:
  - name: API
    autoInstall: true  # Automatically installs missing npm packages

Connection Issues

WebSocket disconnected

The DevAll server stopped or crashed.

Solution: Restart the DevAll server:

npx devall

Can’t connect to dashboard

Firewall or port conflict on port 7777.

Solution: Try a different port:

dashboard:
  port: 8888  # Use a different port

Or via CLI:

npx devall --port 8888

Log Issues

Logs not appearing

Service output might be buffered.

Solution: Ensure your service flushes output:

// Node.js - disable output buffering
process.stdout.write('Starting...\n');

// Python - use unbuffered output
python -u script.py

// Or set environment variable
PYTHONUNBUFFERED=1 python script.py

Logs are cut off

Terminal buffer limit reached (10,000 lines).

Solution: Clear logs periodically or increase buffer in code.

Platform-Specific Issues

Windows: Can’t kill ports

Requires administrator privileges on Windows.

Solution: Run terminal as Administrator or manually kill:

# Find process
netstat -ano | findstr :3000

# Kill process (replace PID)
taskkill /PID 1234 /F

macOS: Permission denied

Missing permissions for certain operations.

Solution: Check file permissions:

# Fix permissions
chmod +x ./script.sh

Linux: Command not found

PATH issues or missing packages.

Solution: Use full paths or install missing tools:

# Use full path
/usr/bin/node server.js

# Or install missing tools
sudo apt-get install lsof  # For port management

Configuration Issues

Config file not found

DevAll can’t find your configuration file.

Solution: Check file location and name:

# DevAll looks for these files (in order):
devall.config.yaml
devall.yaml
devall.yml
devall.jsonc
devall.json
repo.yaml
repo.json

Changes not taking effect

Config cache or syntax errors.

Solution: Restart DevAll after config changes:

# Stop with Ctrl+C, then restart
npx devall

Performance Issues

High CPU usage

Too many services or verbose logging.

Solution: Reduce log output or limit concurrent services:

services:
  - name: API
    autostart: false  # Start manually when needed

  - name: Worker
    secondary: true   # Hide by default

Dashboard is slow

Too much terminal output overwhelming the browser.

Solution: Clear logs regularly or reduce output verbosity:

// Reduce logging in development
if (process.env.NODE_ENV !== 'verbose') {
  console.log = () => {};
}

Common Error Messages

MODULE_NOT_FOUND

Missing npm dependencies.

services:
  - name: API
    autoInstall: true  # Auto-installs missing packages

EADDRINUSE

Port is already in use.

services:
  - name: API
    stealPort: true  # Kills existing process on port

EACCES

Permission denied error.

# Don't use privileged ports (< 1024)
# Use port 3000 instead of port 80

ENOENT

File or directory not found.

services:
  - name: API
    cwd: ./backend  # Check working directory path

Getting More Help

Still stuck? Try these:

1. Check service logs for specific error messages
2. Run DevAll with debug output: DEBUG=1 npx devall
3. Report issues: GitHub Issues
4. Check FAQ: Homepage FAQ