Skip to main content

Troubleshooting

1. Vehicle not appearing in list after adding it​

Symptom: You created a vehicle but it doesn't show up in the Vehicles list.

Causes and fixes:

  • Status filter is active — The vehicle list can be filtered by status. If a filter is set, check that the new vehicle's status matches. Click "Clear Filters" to reset.
  • Creation failed silently — Refresh the page and check if the vehicle exists. If it doesn't, check your browser console for API errors and verify your network connection.
  • Deleted accidentally — Soft-deleted vehicles don't appear in the list. Contact support to recover a recently deleted vehicle.

2. GPS position not updating on the map​

Symptom: The fleet map shows a stale location for a vehicle, or the vehicle doesn't appear on the map at all.

Causes and fixes:

  • GPS Device ID not set — Open the vehicle record and verify the GPS Device ID is filled in and matches exactly what the hardware device sends
  • Device authentication failing — Check your GPS device logs for 401 errors. Verify the API key is active and hasn't expired
  • Device has no cellular signal — Confirm the vehicle has been in an area with coverage. Indoor parking garages or underground locations will lose signal
  • No positions in 90 days — GPS positions expire after 90 days. If a vehicle hasn't moved recently, no current location will show

3. MPG calculation is wrong or missing​

Symptom: The MPG value on a fuel entry is 0, very high, or not calculated.

Causes and fixes:

  • Missing odometer readings — MPG requires consecutive fuel entries with odometer readings. If one or more entries are missing the odometer field, the calculation breaks. Review all fuel entries for the vehicle and fill in missing odometer values
  • Entries out of chronological order — If entries were entered out of order (e.g., you added an older fill-up after a newer one), recalculate by reviewing the sequence
  • Odometer decreased — If an odometer was entered incorrectly and is lower than the previous entry, the MPG will be negative. Correct the odometer field on the wrong entry

4. Alert not generated for maintenance due​

Symptom: A maintenance record is past its due date but no alert appeared.

Causes and fixes:

  • Missing due_date — Alerts only generate for records with a due_date set. Open the maintenance record and confirm Due Date is filled in
  • Wrong status — The maintenance alert timer checks for records with status scheduled or upcoming. If the record is already marked completed or cancelled, no alert is generated
  • Timer hasn't run yet — The maintenance alert timer runs daily at 6:00 AM UTC. If the due date just passed, wait for the next daily run

5. Can't assign a driver to a vehicle​

Symptom: The driver dropdown doesn't show the driver you want to assign, or the assignment doesn't save.

Causes and fixes:

  • Driver is Inactive or Suspended — By default the driver selector may filter to Active drivers only. Check the driver's status and set it to Active if appropriate
  • Driver record doesn't exist yet — You must create the driver in the Drivers module before assigning them to a vehicle. Go to Drivers → Add Driver first
  • Both records need updating — Remember to update both the vehicle (set assigned driver) AND the driver record (set assigned vehicle). They aren't linked automatically

6. Inspection expiry alerts not firing​

Symptom: An inspection is expiring soon but no alert appeared.

Causes and fixes:

  • Expiry date not set — The expiry_date field must be filled in on the inspection record. Open the inspection and verify the expiry date is set
  • Inspection status is Pending — Confirm the inspection has been updated to Passed, Failed, or Requires Attention. Pending inspections are considered incomplete
  • Timer timing — The inspection reminder timer runs daily at 7:00 AM UTC. Alerts are generated before the expiry — check what lead time threshold is configured

7. Cost per mile report shows $0 for a vehicle​

Symptom: The cost-per-mile report shows zero or very low cost for a vehicle that's had maintenance and fuel.

Causes and fixes:

  • No mileage recorded — If the vehicle's current mileage is 0, the cost-per-mile calculation returns 0 (division by zero protection). Update the vehicle's mileage via Edit Vehicle
  • No fuel entries linked — Fuel costs are pulled from Fuel Entry records. Verify fuel entries exist for this vehicle with the correct Vehicle selection
  • Maintenance cost field empty — Maintenance cost is only included if the cost field is set on completed maintenance records. Edit the maintenance records and fill in cost values

8. Purchase order total is wrong​

Symptom: The order total displayed doesn't match what you expect.

Cause: The total is auto-calculated as sum(quantity × unit_price) for all line items. It updates when you edit the order.

Fix: Open the order, click Edit, and verify each line item's quantity and unit price are correct. The total recalculates on save.

9. Integration API returns 401 Unauthorized​

Symptom: External systems calling /api/integration/... receive 401 errors.

Causes and fixes:

  • Missing X-Integration-Key header — Integration endpoints require the X-Integration-Key header. Confirm the calling system is sending this header
  • Wrong key — The key must match exactly what's configured in Fleet Admin. Copy-paste the key rather than retyping it
  • Key revoked or expired — Check the key status in Fleet Admin → API Keys. Generate a new key if needed and update the calling system

10. Vehicle appears on GPS map but shows wrong location​

Symptom: The vehicle pin on the fleet map is in the wrong location or shows a very old position.

Causes and fixes:

  • GPS device sending wrong device ID — Verify the GPS device is sending the correct vehicle association. The vehicle_id in the position payload must match the Fleet vehicle ID
  • Position data corrupted in transit — Check if the device is sending valid latitude/longitude values. The API validates lat (-90 to 90) and lng (-180 to 180) — invalid values are rejected
  • Cached location outdated — The vehicle's current_location cache is updated when new positions arrive. If the device has stopped transmitting, the map shows the last known position. Check device connectivity

When to Contact Support​

Contact The One Stack support for:

  • Data recovery (accidentally deleted vehicles, drivers, or records)
  • API rate limiting or unexpected 429 responses
  • GPS position data not purging after 90 days
  • Cosmos DB connectivity errors
  • Background timer stopped generating alerts unexpectedly

For self-serve investigation, check the Admin section of Fleet for API key status and tenant configuration details.