Skip to content

Troubleshooting

Solutions for common issues you may encounter when using the MAGK platform. Issues are organized by category — find your problem and follow the resolution steps.

TAK Client Connection Issues

Client cannot connect to the server

Symptoms: TAK client shows "Disconnected" or "Connection failed" status. No other players visible on the map.

Solutions:

  1. Verify the server address and port in your TAK client settings. The default SSL port is 8089.
  2. Confirm your certificate is imported correctly — see TAK Client Setup for import instructions.
  3. Test network connectivity to the server: 
    # From a computer on the same network
telnet <server-address> 8089
  4. Switch between WiFi and cellular to rule out local network restrictions.
  5. Check that port 8089 is not blocked by a firewall or corporate network policy.
  6. Restart the TAK client application completely (force close and reopen).

Connection drops intermittently

Symptoms: TAK client connects but disconnects after a few minutes, then reconnects.

Solutions:

  1. Check your network signal strength — weak WiFi or cellular signal causes dropped connections.
  2. Disable battery optimization for your TAK client app (Android: Settings → Apps → ATAK → Battery → Unrestricted).
  3. On iOS, ensure iTAK is allowed background activity in Settings → General → Background App Refresh.
  4. If on a congested network (e.g., event venue with many users), ask your organizer about network capacity.

TCP vs SSL connection confusion

Symptoms: Client connects on the wrong port or protocol. Data appears unencrypted.

Solutions:

  1. Always use SSL protocol on port 8089 unless your organizer explicitly directs otherwise.
  2. Port 8087 is plaintext TCP — only use it for testing or when SSL is unavailable.
  3. In your TAK client, verify the protocol dropdown is set to SSL, not TCP or UDP.

Position not appearing on the tactical map

Symptoms: You are connected but your icon does not appear on the map for other players.

Solutions:

  1. Enable GPS/location services on your device and grant location permissions to the TAK client.
  2. Move outdoors for better GPS signal — indoor GPS reception is unreliable.
  3. Wait 30 seconds after connecting for the initial position report to transmit.
  4. Confirm the event is in Active status — position sharing is disabled for draft events.
  5. Restart the TAK client if the issue persists.

Certificate Errors

"Certificate not trusted" error

Symptoms: TAK client displays a trust error when connecting. Connection is refused.

Solutions:

  1. Verify you imported the certificate for the correct event — each event may use a different Certificate Authority.
  2. Delete the existing certificate from your TAK client and re-import the correct one.
  3. Check that the CA certificate is included in your data package. If you used a .p12 file, you may also need to import the CA certificate separately.
  4. Ask your organizer to re-issue your certificate if the problem persists.

Certificate import fails

Symptoms: TAK client rejects the certificate file during import. Error message about invalid format or wrong password.

Solutions:

  1. Confirm the certificate password matches what your organizer provided — passwords are case-sensitive.
  2. Re-download the certificate file. The file may have been corrupted during transfer.
  3. For .p12 files, ensure the file extension is correct (not renamed to .zip or vice versa).
  4. On iOS, save the .p12 file to the Files app before importing — email attachments may not be accessible from iTAK's file picker.
  5. On Android, try importing the .zip data package instead of the raw .p12 file — ATAK handles data packages more reliably.

Certificate expired

Symptoms: Previously working connection stops with a certificate error. Certificate shows as expired in the client.

Solutions:

  1. Check the certificate expiration date in your TAK client's certificate manager.
  2. Contact your organizer or admin to issue a new certificate.
  3. Delete the expired certificate and import the replacement.
  4. Admins: navigate to Admin → Certificates to view expiration dates and re-issue certificates. See Certificates.

Certificate revoked

Symptoms: Connection fails after previously working. Admin revoked your certificate.

Solutions:

  1. Contact your event organizer to understand why the certificate was revoked.
  2. If a new certificate is issued, delete the old one from your TAK client and import the replacement.
  3. Revocation takes effect on the next connection attempt — if you're still connected, you'll be disconnected when the session ends.

Device Pairing and Provisioning Failures

Node device not detected during provisioning

Symptoms: The MAGK Node does not appear in the Unprovisioned Devices list.

Solutions:

  1. Confirm the node is powered on and connected to the provisioning network.
  2. Verify the node and the MAGK server are on the same network or that UDP port 5683 is routable between them.
  3. Check the node's LED indicator for status — refer to your hardware documentation for LED codes.
  4. Restart the node device and wait 30 seconds for it to broadcast its presence.
  5. Check Admin → Logs for any node discovery errors.

Provisioning fails with an error

Symptoms: Provisioning starts but the status changes to Error. The device does not come online.

Solutions:

  1. Check the provisioning logs at Admin → Nodes → Provisioning Logs for the specific error message.
  2. Common causes:
    • Network timeout — The node lost connectivity during provisioning. Retry the operation.
    • Incompatible firmware — The selected firmware version is not compatible with the hardware. Try a different firmware version.
    • Configuration template error — A required field (e.g., Server URL) is missing in the template. Edit the template and retry.
  3. Re-provision the device after resolving the underlying issue.

Node shows "Offline" after successful provisioning

Symptoms: Provisioning completed successfully but the node status is Offline.

Solutions:

  1. Verify the node's network connection — it must reach the MAGK server on the configured UDP port (default: 5683).
  2. Check that the Server URL in the configuration template points to the correct MAGK server address.
  3. Confirm no firewall is blocking UDP traffic on port 5683.
  4. Review Admin → Infrastructure for any service health issues.
  5. Re-provision the node if the configuration was incorrect.

Web UI Issues

Page loads with a blank screen or errors

Symptoms: The MAGK web interface shows a white screen, loading spinner that never completes, or JavaScript errors in the browser console.

Solutions:

  1. Hard-refresh the page: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS).
  2. Clear your browser cache and cookies for the MAGK domain.
  3. Try a different browser or incognito/private window to rule out extension conflicts.
  4. Check the browser developer console (F12 → Console tab) for error messages and share them with your admin.

Login fails or session expires immediately

Symptoms: You enter correct credentials but are redirected back to the login page, or your session expires within seconds.

Solutions:

  1. Verify your account is active — deactivated accounts cannot log in. Contact your admin.
  2. Clear browser cookies for the MAGK domain and try again.
  3. Check that your browser allows cookies — session authentication requires cookies.
  4. Admins: verify the BETTER_AUTH_SECRET and BETTER_AUTH_TRUSTED_ORIGINS values in .env are correct. Mismatched trusted origins cause session rejection.

Tactical map does not load or shows no tiles

Symptoms: The map area is blank, grey, or shows broken tile images.

Solutions:

  1. Check your internet connection — map tiles are loaded from external providers.
  2. If using MapTiler or Mapbox, verify the API key is configured in Admin → Settings.
  3. The default provider (OpenStreetMap) requires no API key. If tiles still fail, the OSM tile server may be temporarily unavailable.
  4. Try switching map layers (street → satellite → hybrid) to see if a specific layer is the issue.
  5. Check the browser console for CORS or 403 errors indicating an invalid or expired API key.

Real-time updates not working

Symptoms: Scoreboard, map markers, or event status do not update in real time. Data only refreshes on page reload.

Solutions:

  1. Check the WebSocket connection indicator in the UI (if available). A disconnected state means real-time updates are paused.
  2. Verify your browser supports WebSocket connections and no proxy or firewall is blocking them.
  3. Admins: check that the WebSocket gateway service is running — see Admin → Infrastructure.
  4. Admins: verify RabbitMQ is healthy — the WebSocket gateway depends on RabbitMQ for message delivery.

Docker and Deployment Issues

docker compose build fails for the docs service

Symptoms: The docs container fails to build with MkDocs errors.

Solutions:

  1. Check the build output for the specific error. Common causes:
    • Missing Markdown file — A file referenced in mkdocs.yml nav does not exist. Create the missing file or remove the nav entry.
    • Invalid YAML — Syntax error in mkdocs.yml. Validate with a YAML linter.
    • Plugin error — A required MkDocs plugin is not installed. Check requirements.txt.
  2. Run the build locally to debug: 
    docker compose build docs

Container fails health check and keeps restarting

Symptoms: A service shows as "unhealthy" in docker ps. The container restarts repeatedly.

Solutions:

  1. Check container logs for the failing service: 
    docker compose logs <service-name> --tail 50
  2. Common causes:
    • Database not ready — The service started before PostgreSQL was available. Wait for the database to initialize, or check depends_on configuration.
    • Missing environment variables — A required .env variable is not set. Compare your .env against .env.template.
    • Port conflict — Another process is using the same port. Check with lsof -i :<port> or netstat -tlnp.
  3. Restart the specific service: 
    docker compose restart <service-name>

Traefik returns 502 Bad Gateway

Symptoms: Accessing the MAGK web UI or docs site returns a 502 error.

Solutions:

  1. Verify the target service is running: 
    docker compose ps
  2. Check that the service is on the correct Docker network (magk-network and t3_proxy).
  3. Review Traefik logs for routing errors: 
    docker compose logs traefik --tail 50
  4. Confirm the Traefik labels in the compose file match the expected host rule and port.
  5. If the service recently restarted, wait for the health check to pass before Traefik routes traffic to it.

SSL certificate errors in the browser

Symptoms: Browser shows "Your connection is not private" or certificate warning when accessing the MAGK site.

Solutions:

  1. Verify the DOMAIN and SSL_EMAIL values in .env are correct.
  2. Check that DNS records for your domain point to the server's IP address.
  3. Review Traefik logs for Let's Encrypt certificate issuance errors: 
    docker compose logs traefik --tail 100 | grep -i "acme\|certificate\|letsencrypt"
  4. Ensure ports 80 and 443 are open — Let's Encrypt requires these for certificate validation.
  5. For Route53 DNS validation, verify the AWS credentials and hosted zone configuration.

Voice Communications (Mumble)

Server shows "Disconnected" in admin panel

Symptoms: The Voice admin page shows the server status as "Disconnected" or "Disabled".

Solutions:

  1. Verify MUMBLE_ENABLED=true is set in your .env file.
  2. Check that the magk-mumble container is running and healthy: 
    docker compose ps magk-mumble
  3. Check the Ice Admin Sidecar logs for connection errors: 
    docker compose logs magk-mumble-admin --tail 50
  4. If the status shows "Disabled", the MUMBLE_ENABLED variable is not set to true. Update .env and restart the stack.
  5. Verify the Ice RPC port (6502) is accessible between containers on the Docker network.

Players cannot authenticate

Symptoms: Players receive "Invalid username or password" when connecting to the Mumble server.

Solutions:

  1. Verify MUMBLE_LDAP_ENABLED=true is set in your .env file.
  2. Confirm the roster has been finalized for the event — LDAP credentials are provisioned during finalization.
  3. Check that the player's Mumble username matches their roster assignment (visible on their profile page).
  4. Check the Ice Admin Sidecar logs for LDAP bind errors: 
    docker compose logs magk-mumble-admin --tail 50 | grep -i "ldap\|auth"
  5. Verify the OpenLDAP container is healthy: 
    docker compose ps magk-openldap

One-way audio (can hear but not be heard, or vice versa)

Symptoms: Voice communication only works in one direction. Players can hear others but their own voice doesn't transmit, or they can transmit but hear nothing.

Solutions:

  1. Ensure UDP port 64738 is forwarded on your router/firewall. Mumble uses UDP for voice data — TCP alone causes one-way audio.
  2. Check that no VPN or corporate firewall is blocking UDP traffic on port 64738.
  3. Verify the MUMBLE_EXTERNAL_PORT value matches the port forwarded on your router.
  4. For ATAK Vx plugin users, check microphone permissions in Android settings.
  5. Try connecting from a different network (cellular vs. WiFi) to isolate the issue.

Vx plugin shows certificate error

Symptoms: The ATAK Vx plugin refuses to connect with a certificate trust error.

Solutions:

  1. If using MUMBLE_CERT_MODE=self-signed, the Vx plugin may not trust the certificate. Switch to MUMBLE_CERT_MODE=ca for CA-signed certificates.
  2. Re-import the TAK data package — it includes the Mumble TLS certificate in the trust store.
  3. Verify the Mumble TLS certificate includes the extendedKeyUsage server authentication extension.
  4. Clear the Vx plugin's certificate cache and reconnect.
  5. As a last resort, manually trust the certificate in ATAK's security settings.

Channels not provisioned after roster finalization

Symptoms: Roster finalization completes but no Mumble channels appear in the Voice admin page.

Solutions:

  1. Verify the event has Enable Mumble Voice checked in the Communications settings.
  2. Check the web service logs for provisioning errors: 
    docker compose logs magk-web --tail 100 | grep -i "mumble\|provision"
  3. Verify the Ice Admin Sidecar is reachable from the web service.
  4. Try deprovisioning and re-finalizing the roster from the event's Communications section.

Connected users not visible in admin panel

Symptoms: Players are connected to Mumble but the admin panel shows no connected users.

Solutions:

  1. If using the monitoring bot (MUMBLE_MONITORING_ENABLED=true), check its container logs: 
    docker compose logs magk-mumble-monitor --tail 50
  2. Without the monitoring bot, connected user data comes from Ice RPC queries. Verify the sidecar is healthy.
  3. Refresh the Voice admin page — user data updates in real time via WebSocket when the monitoring bot is active.

Getting More Help

If your issue isn't covered here:

  1. Check the FAQ for quick answers to common questions
  2. Review the relevant guide for your role:
  3. Check Admin → Logs for system-level error messages
  4. Contact your event organizer for event-specific issues