Common Issues

Quick solutions to the most frequently reported problems.

Router shows "Offline" in the dashboard

Cause: The WireGuard VPN tunnel is not established or has dropped.

Solutions:

1. In MikroTik terminal, check the WireGuard peer status:

   /interface wireguard peers print

   If last-handshake is empty or more than 5 minutes ago, the tunnel is down.
2. Verify the router's internet connection: try pinging 8.8.8.8 from the terminal.
3. Check if UDP port 13231 is blocked by your upstream ISP firewall.
4. Re-run the Qserve setup script from the Site installation page — it is safe to run again.

M-Pesa STK push prompt not appearing on subscriber's phone

Cause: Phone number format error, Daraja credentials issue, or Safaricom service disruption.

Solutions:

• Confirm the phone number is entered as 254XXXXXXXXX (no + prefix, correct country code).
• Check that your Daraja app environment is set to Production (not Sandbox) for live payments.
• Verify your passkey and shortcode are correct in Settings → Payment Platforms.
• Test via the Daraja API console to rule out a Safaricom outage.

Subscriber can't connect after activation

Cause: PPPoE credentials not synced to router, or the router went offline after activation.

Solutions:

1. Confirm the router is Online in the dashboard — if offline, fix the VPN first.
2. Open the subscriber profile → click Sync to Router to force a credential push.
3. In MikroTik, check if the PPPoE secret exists:

   /ppp secret print where name="subscriber-username"

4. Verify the subscriber is using the correct username and password (check for typos).

PPPoE sessions drop every few hours

Cause: Keepalive timeouts on the router, or the Qserve RADIUS session timeout is too short.

Solutions:

• In Qserve Settings, increase the RADIUS Session Timeout to 86400 (24 hours) or higher.
• In MikroTik PPPoE settings, enable keepalive and set the timeout to match.
• Check if the subscriber's physical link (fiber/wireless) has packet loss — intermittent drops at layer 1 cause PPPoE disconnects.

Hotspot captive portal not loading

Cause: DNS interception not working, or the MikroTik hotspot interface is not properly bound to the WiFi network.

Solutions:

1. Verify the subscriber's device is connected to the hotspot's WiFi SSID (not another network).
2. Confirm the MikroTik hotspot is bound to the correct bridge interface (the one serving WiFi clients).
3. Try opening http://1.1.1.1 manually — if this redirects to the portal, the device's browser may be blocking HTTP redirects for HTTPS pages. Advise the user to try a different browser.
4. Re-run the hotspot setup script from the Site installation page.

SMS notifications not being sent

Cause: SMS provider credentials are incorrect, or account balance is depleted.

Solutions:

• Go to Settings → SMS → click Test SMS to get a diagnostic error message.
• Log in to your SMS provider account (e.g., AfricasTalking) and check account balance and API logs.
• Confirm the API key has not been regenerated in the provider dashboard.

Dashboard is slow or not loading

Cause: Browser cache issue, or a large number of subscribers causing slow queries.

Solutions:

• Try a hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac).
• Clear your browser cache and cookies.
• Try a different browser or incognito mode.
• If the issue persists, contact support — there may be a server-side issue.