Troubleshooting

Common issues and how to fix them. Can't find your problem? Open an issue on GitHub.

Server Won't Start

Port Already in Use

If you see Error: EADDRINUSE :::3456, another process is using port 3456.

# Find what's using the port
# Windows:
netstat -ano | findstr :3456

# macOS/Linux:
lsof -i :3456

# Option 1: Kill the conflicting process
# Option 2: Use a different port
PORT=3457 node server.js

Node.js Version Too Old

Uplink requires Node.js v18 or later. Check your version:

node --version
# If below v18, update from https://nodejs.org

Missing Dependencies

If you see MODULE_NOT_FOUND errors, your node_modules may be incomplete:

# Delete and reinstall dependencies
rm -rf node_modules
npm install

Sharp Install Fails

Sharp is an optional dependency used for image compression. If it fails to install with native build errors, that's OK — Uplink works fine without it. Images will just be sent at their original size.

If you want image compression and Sharp won't install:

• macOS: xcode-select --install to get build tools, then retry npm install sharp
• Windows: Install Visual C++ Build Tools, then retry
• Linux / WSL2: sudo apt install build-essential, then retry
• Still failing: Skip it. Everything else works without Sharp.

Messages Not Working

Gateway Connection Failed

If the UI loads but messages fail with a connection error, Uplink can't reach the OpenClaw gateway.

• Check that OpenClaw is running: openclaw gateway status
• Verify the Gateway URL in Settings → Connection matches your OpenClaw setup
• Default gateway URL is http://127.0.0.1:18789
• Try opening the gateway URL in your browser — you should see a JSON response

Slow or Hanging Responses

If messages take a very long time or seem to hang:

• The AI model may be loading — first message after startup is always slower
• Check your model's resource requirements vs. your hardware
• Open the browser's developer console (F12) to see if there are WebSocket errors
• Try reducing the context window or switching to a smaller model

Voice Chat Issues

TTS Not Working

If you don't hear voice responses:

1. Check Settings → Voice to confirm a TTS engine is selected
2. If using Edge TTS: Make sure you have internet access and node-edge-tts is installed
3. If using XTTS: Verify the XTTS server is running and the URL is correct (default: http://localhost:8020)
4. If using OpenAI TTS: Verify your API key is valid
5. If using ElevenLabs: Verify your API key is valid and you have remaining quota
6. If using Piper: Verify PIPER_MODEL points to a valid .onnx model file
7. Check browser audio permissions — Uplink needs permission to play audio

# Test your XTTS server directly
curl http://localhost:8020/api/tts -X POST \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello", "language": "en"}' \
  --output test.wav

# If this fails, the issue is with your XTTS server, not Uplink

STT Not Working (Microphone)

If voice input doesn't transcribe:

• Check browser microphone permissions — the browser must allow access
• If using faster-whisper: Verify the server is running and URL is correct in Settings → Voice & TTS
• If using OpenAI Whisper STT: Verify your OpenAI API key is valid and has remaining credits
• If using Groq STT: Verify your Groq API key is valid and the Groq service is reachable
• If using Browser STT: Make sure you're using Chrome or Edge — Firefox and Safari have limited Web Speech API support
• On mobile: Make sure the PWA has microphone permissions in your device settings
• On mobile over Tailscale: Use the HTTPS URL (https://...ts.net:3457) — browsers require HTTPS for microphone access

Voice Latency Too High

If there's a long delay between speaking and hearing a response:

Remote Access Issues

Can't Connect from Another Device

If other devices on your network can't reach Uplink:

1. Verify both devices are on the same Wi-Fi / LAN (or both on Tailscale)
2. Check that Uplink is bound to 0.0.0.0 — by default it only listens on localhost. Enable Network Access in Settings → Server, or set UPLINK_HOST=0.0.0.0 in your environment or .env file. Enabling authentication (UPLINK_AUTH_ENABLED=true) also automatically binds to 0.0.0.0. See Network Binding.
3. Check your firewall (see Remote Access)
4. Try using the IP address directly — not hostname
5. Make sure you're using port 3456 (or 3457 for Tailscale HTTPS)
6. If exposing to untrusted networks, enable authentication: set UPLINK_AUTH_ENABLED=true and UPLINK_AUTH_TOKEN=<your-long-random-token>

Page Loads But "No Response Received"

If you can see the Uplink UI and send messages, but responses never come back:

This usually means GATEWAY_URL in your .env file is set to a non-localhost address (like your Tailscale IP). The OpenClaw gateway only listens on 127.0.0.1, so Uplink can't proxy your messages to it.

# ✅ Correct
GATEWAY_URL=http://127.0.0.1:23248

# ❌ Wrong — causes "No response received"
GATEWAY_URL=http://100.85.40.53:23248

The gateway URL should always be localhost, even when accessing Uplink remotely. Uplink handles the proxying — remote clients talk to Uplink, and Uplink talks to the gateway locally.

WebSocket Disconnections

If conversations stop syncing or the UI shows "disconnected":

• Refresh the page — WebSocket will reconnect automatically
• If using Tailscale, check that the VPN tunnel is active
• Unstable Wi-Fi can cause frequent disconnects — try a wired connection

Encryption Issues

Forgot Encryption Password

If you enabled encryption and forgot your password, your conversations cannot be recovered. This is by design — zero-knowledge encryption means the server cannot decrypt your data.

Your options:

• If you have a backup of the database from before encryption, restore it
• Reset the database and start fresh (you'll lose all encrypted conversations)

Browser Compatibility

Uplink works in all modern browsers. Known quirks:

Crash Recovery

Uplink includes a built-in watchdog that automatically restarts the server if it crashes unexpectedly. If you notice Uplink went down and came back on its own, the watchdog handled it. Check the server logs for crash details — the watchdog logs restart events so you can investigate the root cause.

Getting Help

If none of the above resolves your issue:

1. Check the browser console (F12 → Console) for error messages
2. Check the Node.js terminal output for server-side errors
3. Open an issue on GitHub with:
   • Your OS and Node.js version
   • Steps to reproduce the issue
   • Any error messages from the browser console or server terminal
4. Join the Discord server for community support