Docs

Troubleshooting

DevApp Is Not Loading

Symptom: Browser shows a connection error or blank page at http://localhost:3003.

Steps:

  1. Check that the agent is running: 
    fenwave service status
  2. If stopped, start it: 
    fenwave service start
  3. Check the DevApp container status: 
    fenwave local-env --status
  4. If the container is not running, start it: 
    fenwave local-env --start
  5. Check the DevApp logs for errors: 
    fenwave local-env --logs

Agent Shows “Disconnected” in the UI

Symptom: The status bar in the DevApp shows “Disconnected”.

Possible causes:

  • The agent process has stopped
  • The WebSocket port (3001) is blocked by a firewall or in use by another process

Steps:

  1. Verify the agent is running: 
    fenwave service status
  2. If the agent is running but the UI is still disconnected, check which port the agent is using: 
    fenwave info
  3. If port 3001 is blocked, configure a different port: 
    fenwave config set --ws-port 3005
fenwave service restart
  4. Reload the DevApp page in your browser.

Cannot Pull an Image

Symptom: Image pull fails with an authentication error or “image not found”.

Steps:

  1. For private registries, verify the registry is connected in the Registry section.
  2. Check that the image reference is correct, including the full registry host and tag.
  3. For AWS ECR, confirm your AWS credentials have the ecr:GetAuthorizationToken and ecr:BatchGetImage permissions.
  4. Check agent logs for detailed error output: 
    fenwave service logs --tail 50

Logs Are Empty or Not Streaming

Symptom: The Logs panel shows no output for a running container.

Steps:

  1. Ensure the container is writing to stdout/stderr (some apps write to files only).
  2. Try increasing the tail count — logs may exist but are older than the current tail window.
  3. Check the agent connection status — if disconnected, log streaming is paused.

DevApp Port Conflict

Symptom: DevApp fails to start because port 3003 is already in use.

Steps:

  1. Change the DevApp container port: 
    fenwave config set --container-port <available_port>
fenwave service restart
  2. Access the DevApp at the new port: http://localhost:<available_port>.

Still Stuck?

View full agent logs:

fenwave service logs -f

Enable debug mode for verbose output:

fenwave service run --debug

Or check the Fenwave Agent Troubleshooting guide for agent-level issues.