Troubleshooting & FAQ
Common issues, step-by-step resolution procedures, toast message reference, and validation error quick reference.
Last updated April 17, 2026
Troubleshooting Guide
This guide covers the most common issues encountered when operating the OpenVTS platform, with step-by-step resolution procedures for each scenario.
Vehicle Not Appearing on Map
- Verify the vehicle status is Active (not Inactive) in the Vehicles module
- Check that a device IMEI is linked to the vehicle in the vehicle detail
- Confirm the device is powered on and has cellular connectivity (check Device Status: Connected/Disconnected)
- Verify the vehicle has a valid plan — vehicles with 'License Required' status are blocked from tracking
- Check the Last Update timestamp — if it shows days/hours ago, the device may be offline or out of coverage
Device Disconnected
- Verify the SIM card is active with the cellular provider and has data balance
- Check the device type and protocol in Master Data — ensure the listener port matches
- Confirm the server's listener service is running in Superadmin > Server
- Verify the APN settings on the device match the SIM provider's APN configuration
- Check for firmware compatibility — compare device firmware against the supported version in Device Types master data
- Review Telemetry Logs for any raw packets from this IMEI to determine if data is arriving but not parsing
Alerts Not Firing
- Verify the alert type is enabled for the specific vehicle in Notifications settings
- Check that at least one notification channel is enabled (Web Push, Mobile Push, WhatsApp, Email)
- For overspeed alerts, confirm the speed limit (kph) threshold is set correctly
- For geofence alerts, verify the geofence is set to Active in Landmarks Studio
- For email alerts, verify SMTP is configured and validated in Settings > SMTP (use Validate SMTP button)
- For WhatsApp alerts, verify the WhatsApp API is configured and the template is approved (Synced status)
- For push notifications, check the pushRegistered status — user must have granted browser permission
- Review Vehicle Events logs to check if alerts were generated but delivery failed (check delivery log status)
Sensor Showing Error
- Open the sensor in edit mode and check the JavaScript code for syntax errors
- Use the Sensor Playground to test the code against sample data
- Verify the telemetry payload contains the expected attribute keys (check first 200 attributes in the data panel)
- Check for 'Invalid payload' warnings — the device may be sending malformed data
- Ensure the sensor code handles edge cases (null values, missing keys, division by zero)
Wrong Speed or Distance Values
- Check the Speed Multiplier (speedX) and Distance Multiplier (distanceX) values in Vehicle > Config — they should be 1.0 unless intentional adjustment is needed
- Verify the Ignition Source setting — 'Motion Based' derives ignition from speed threshold and may differ from 'Ignition Wire' (hardware sensor)
- Review the Set Odometer and Set Engine Hours values — incorrect overrides can cause cumulative drift
Emails Not Sending
- Verify SMTP Status is toggled to Active in Settings
- Check the SMTP Type (NONE/SSL/TLS) matches your email provider's requirements
- Confirm the Host, Port, Username, and Password are correct
- Use the Validate SMTP button and send a test email to verify delivery
- Check the Reply To and Email fields — some providers reject mismatched sender addresses
Quick Reference Table
| Issue | First Check | Module |
|---|---|---|
| Vehicle not tracking | Is device IMEI linked? | Vehicles > Profile |
| Map shows wrong position | Check Lat/Long in vehicle details | Maps > Vehicle Dock |
| Plan expired | Renew vehicle plan | Payments > Renew |
| User cannot login | Check account status and credentials | Users |
| Driver not assigned | Check Current Assignment | Drivers > Assignment |
| Geofence not alerting | Is geofence Active? | Landmarks Studio |
| Report empty | Check date range and vehicle selection | Reports |
| WhatsApp not delivering | Is template Synced with Meta? | WhatsApp Templates |
| AI Agent not responding | Check OpenRouter API key and model | Settings > API Config |
| SSL certificate expired | Renew certificate | Superadmin > SSL |
All Validation Error Messages
| Rule | Description | Applies To |
|---|---|---|
| required | Field cannot be empty | All required fields |
| minLength | Value is shorter than minimum | Names, descriptions, codes |
| maxLength | Value exceeds maximum length | All text inputs |
| mustContainLetter | Must include at least one letter | Names, usernames, company names |
| invalidChars | Contains disallowed characters | Names, usernames |
| noMultipleSpaces | No consecutive spaces allowed | Name fields |
| validEmail | Must be a valid email format | Email fields |
| validUrl | Must be a valid URL format | URL fields |
| mustBeNumber | Value must be numeric | Amounts, coordinates, digits |
| mustBePositive | Value must be greater than zero | Amounts, radius, tolerance |
| rangeExceeded | Value outside allowed range | Lat (-90-90), Lng (-180-180), Zoom (1-20) |
| passwordMismatch | Passwords do not match | Confirm password fields |
| fileTooLarge | File exceeds size limit | Document uploads |
| invalidFileType | File type not supported | Upload fields |
Tip
When troubleshooting, always check the Activity Logs (Logs Explorer > Activity Logs) for recent error events related to the issue. The metadata field often contains the root cause details.
Tip
For device connectivity issues, the Telemetry Logs tab is your best diagnostic tool. Filter by IMEI to see raw packets and determine if data is arriving at the server.