> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/help-center/troubleshooting.md).

# Troubleshooting

This guide covers common issues and their solutions.

### 1. Telemetry Not Appearing on Map

If you are not seeing real-time updates for your devices:

* **Check Device Status:** In the **Devices** page, check the "Last Seen" timestamp. If it is "Never," the backend has not yet received a valid packet.
* **Verify UDP Ingestion:**
  * Ensure your device is sending UDP packets to the correct IP address and Port (default: `9000`).
  * Check for firewall rules on your EC2 instance or local network that might be blocking UDP traffic.
* **HMAC Authentication:**
  * Ensure the shared secret (32-byte HEX) on the device exactly matches the one registered in the AdaTrack backend.
  * Verify that the device's clock is synchronized with a real-time clock (RTC) or GPS time. If the device timestamp is off by more than 5 seconds, the packet will be rejected.
* **Decoder Errors:**
  * Navigate to **Device Profiles** and check the "Decoder Logs" for your profile. Any syntax or runtime errors in your JavaScript decoder will prevent the data from being persisted.

### 2. Dashboard Shows "No Data" (Self-hosted)

This typically indicates an issue with the monitoring stack (Prometheus/Grafana):

* **Verify Backend is Running:** Run `ps aux | grep server` or `sudo docker ps | grep backend`.
* **Test Metrics Endpoint:** Run `curl http://localhost:8080/metrics`. It should return a list of Prometheus-formatted metrics.
* **Check Prometheus Targets:** Visit `http://localhost:9090/targets` in your browser. The `iot-backend` target should be **UP**.
* **Grafana Data Source:** Ensure the Prometheus data source in Grafana is correctly configured (usually `http://prometheus:9090`).

### 3. Geofence Alerts Not Triggering

* **Verify GPS Accuracy:** Geofence alerts require a valid GPS coordinate. If your device's GPS fix is poor, its reported location may be outside the geofence boundary or have high horizontal dilution of precision (HDOP).
* **Check Geofence State:** Ensure the geofence is **Active** and that the device is correctly associated with it.
* **Trigger Logic:** Remember that geofence alerts are triggered by a *crossing event* (Entering or Exiting). If a device is already inside a geofence when it is created, an "Entry" event will not be triggered until it first exits and re-enters.

### 4. Report Generation Failed

* **Check Time Range:** Ensure the requested report has a valid time range with existing telemetry data.
* **Account Quotas:** Verify that your account has not exceeded the monthly "Report Generation Quota."
* **Storage Configuration:** For self-hosted deployments, ensure the backend has write permissions to the `/reports` directory or that the S3 bucket configuration is correct.

### 5. Database or Schema Issues (Self-Hosted)

If you suspect database problems — missing tables, failed migrations, or degraded performance — use the built-in health check:

```bash
adatrack-ctl doctor
```

This runs diagnostic checks across schema integrity, TimescaleDB health, storage bloat, connection utilization, cache hit ratio, and host kernel settings. Each check reports PASS, WARN, or FAIL with an explanation.

For specific issues:

* **"Schema is dirty":** A previous migration failed partway through. Fix the underlying issue, then run:

  ```bash
  adatrack-ctl upgrade --force
  ```
* **Missing tables after upgrade:** Verify the schema version matches what you expect:

  ```bash
  adatrack-ctl status
  ```

  If migrations are pending, apply them with `adatrack-ctl upgrade`.
* **High table bloat:** The doctor will flag tables with excessive dead tuples. Run `VACUUM ANALYZE` on the affected tables.
* **Export diagnostics for support:**

  ```bash
  adatrack-ctl doctor --json > diagnostics.json
  ```

For more details, see the [adatrack-ctl reference](https://github.com/AdaTrack/adatrack_platform/tree/main/docs/gitbook/documentation/getting-started/adatrack-ctl.md).

***

### Still Having Issues?

Check your backend logs for specific error messages:

```bash
# If running with systemd
sudo journalctl -u iot-backend -f

# If running with Docker
docker logs -f adatrack_backend
```

Look for keywords like `[ERROR]`, `[REJECT]`, or `[PANIC]`.