Docs

Troubleshooting

Common Issues

Agent won’t start

Symptom: fenwave service start or fenwave service run fails.

Possible causes:

Cause Solution
Not logged in Run fenwave login
Session expired Run fenwave login to re-authenticate
Device not registered Run fenwave init or fenwave register
Docker not running Start the Docker daemon (run systemctl start docker)
Port already in use Use --port <port> to specify a different port, or stop the process using the default port
Stale lock file The agent detects and cleans stale locks automatically. If the issue persists, delete ~/.fenwave/daemon/agent.lock

Cannot log in

Symptom: fenwave login opens the browser but authentication fails or times out.

Check:

  1. Is the Fenwave IDP backend running and accessible? 
    curl -s <backend-url>
  2. Is the frontend URL correct? 
    fenwave config show
  3. Is the loopback port (49152–49251) blocked by a firewall?
  4. Did the login timeout (default: 60 seconds)? Try again — the browser may have been slow to load.

DevApp dashboard not loading

Symptom: The agent starts but http://localhost:3003 shows nothing.

Check:

  1. Is the DevApp container running? 
    fenwave containers
  2. Is Docker running? 
    docker ps
  3. Is the container port correct? 
    fenwave config show
  4. Check container logs for errors: 
    fenwave local-env --logs

WebSocket connection failed

Symptom: The DevApp dashboard loads but shows “Agent Disconnected” or cannot perform operations.

Check:

  1. Is the agent still running? 
    fenwave service status
  2. Is the WebSocket port accessible? 
    fenwave config show    # Check wsPort value
  3. Check if the ws-token file exists: 
    ls ~/.fenwave/ws-token
  4. Restart the agent to regenerate the token: 
    fenwave service restart

Registration failed

Symptom: fenwave init or fenwave register fails.

Possible causes:

Cause Solution
Invalid or expired token Generate a new token from the IDP (valid for 7 days)
Token already used Each token is single-use; generate a new one
Backend unreachable Check --backend-url value and network connectivity
Device already registered Use fenwave rotate-credentials to refresh, or fenwave uninstall and re-register

Permission errors during install

Symptom: npm install -g fails with EACCES or permission denied.

Solutions (pick one):

  1. Install nvm (recommended): 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 20
nvm use 20
  2. Change npm prefix: 
    mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
  3. Use sudo (not recommended): 
    sudo npm install -g @fenwave/agent

Debug Mode

For detailed logging, enable debug mode:

# Via CLI flag
fenwave service run --debug

# Via environment variable
DEBUG=true fenwave service start
FW_VERBOSE=true fenwave service start

Debug mode prints additional information about:

  • HTTP requests to the backend
  • WebSocket message routing
  • Session validation checks

Resetting Everything

If all else fails, you can perform a clean reset:

# 1. Stop the agent
fenwave service stop

# 2. Remove all agent data
fenwave uninstall

# 3. Re-run setup
fenwave init --token <new-token> --backend-url <url>

# 4. Log in
fenwave login

# 5. Start the agent
fenwave service start

fenwave uninstall removes all local data including device credentials, session, and configuration. You will need a new registration token to set up again.