Troubleshooting

Common issues and how to fix them.

Payloads not appearing

First, confirm the Fanar desktop app is running and the feed is not paused (press Space to toggle).

Then verify the HTTP server is reachable from your app:

curl -s -o /dev/null -w "%{http_code}" \
  -X POST http://localhost:23517/api/payloads \
  -H "Content-Type: application/json" \
  -d '{"type":"log","label":"test","content":""ping""}'
# Expected: 201

If this returns 201 but payloads still don't show, check that no active type filter or search is hiding them — the filter buttons in the top bar show active counts.

Port conflict

If another process is already using port 23517, Fanar fails to start its HTTP server. Check what's on the port:

# macOS / Linux
lsof -i :23517

# Windows
netstat -ano | findstr :23517

Either stop the conflicting process, or change Fanar's port in Preferences → Port. After changing the port, update your client configuration to match.

App running in Docker or a VM

Your containerised app cannot reach localhost:23517 on your laptop directly — localhost inside the container refers to the container itself.

  • Docker Desktop (Mac/Windows) — use host.docker.internal as the Fanar host.
  • Linux Docker — add extra_hosts: ["host.docker.internal:host-gateway"] to your compose file, then use host.docker.internal.
  • Remote VM / staging server — use the SSH tunnel instead of a direct host/port.

Firewall blocking the port

On some machines a firewall blocks inbound connections to 23517. Fanar only needs to be reachable from the machine running your app — usually localhost, which bypasses firewall rules. If you are connecting from a different machine over LAN, allow the port:

# Ubuntu / Debian
sudo ufw allow 23517

# macOS — add a rule in System Settings → Network → Firewall

CORS errors in a browser app

Fanar's HTTP server allows all origins (Access-Control-Allow-Origin: *), so CORS should never be an issue. If you see a CORS error it usually means the request is going to the wrong port or the Fanar server is not running.

SSH tunnel not connecting

See the SSH Tunnel troubleshooting section.

VS Code file links not opening

Clicking a file:line link in the feed opens vscode://file/…. This requires VS Code to be installed and registered as a URI handler. On Linux, run:

code --install-extension # any extension install triggers the URI registration
# or open VS Code once manually so it registers the vscode:// handler

On macOS and Windows, VS Code registers the URI handler automatically on first launch.

Still stuck?

Open an issue on GitHub with your OS, Fanar version, and the output of the curl test above.

←
Previous
SSH Tunnel