Skip to content
roitrack docs

Common issues

“License already in use on another server”

Your license pinned to a previous server IP. Unpin it from the portal and retry.

Admin panel shows “License required” or won’t load

Check the container logs on your VPS:

Terminal window
cd /opt/roitrack
docker compose logs -f fastapi-api --tail 100

Look for license_state.hard_blocked=true (IP-pin issue), grace_expired (payment issue — check the portal), or a network error (license-server unreachable).

Postbacks aren’t firing

  1. Check the Conversions page in the admin panel — does the raw postback URL match what you gave the affiliate network?
  2. In the network’s postback log, confirm they’re actually calling it
  3. Confirm the clickid matches — networks that URL-encode or truncate can silently break attribution

Clicks are recorded but conversions never show

Almost always a clickid mismatch or a S2S postback URL misconfiguration. See above.

Installer failed halfway

Re-run the install command — the installer is idempotent. If it fails again, grab the last 20 lines of output and email support@roitrack.app with your license key.

Docker containers keep restarting

Terminal window
docker compose ps
docker compose logs --tail 50 CONTAINER

Common cause: not enough RAM. roitrack needs 4 GB minimum. If you’re on a 2 GB VPS, either upgrade or enable swap.

Update failed / stuck on old version

Check your license is active in the portal — updates are gated behind license validation. If active, re-run:

Terminal window
cd /opt/roitrack
./update.sh