Troubleshooting¶

If nothing here matches what you are seeing, check the FAQ, search existing GitHub issues, or file a bug report with your Home Assistant version, the integration version, and the relevant log lines (see Reading the logs below).

Setup and config flow¶

"Failed to connect to AutoPi API"¶

The config flow shows this when the initial connection test to the AutoPi API fails before it can even check the key.

1. Confirm Home Assistant has outbound internet access - the integration is cloud_polling; it has no local mode and cannot work offline.
2. If you set a custom Base URL during setup, check it's reachable and correct. Leave it blank to use the default https://api.autopi.io.
3. Retry - transient AutoPi API outages surface as this same error.

"Invalid API key"¶

The config flow's authentication test received a 401 from the AutoPi API.

1. Regenerate the token at app.autopi.io under Account Settings → API Tokens and paste the new value in exactly - no surrounding whitespace.
2. Confirm the token hasn't expired or been revoked from the AutoPi dashboard.

"No vehicles found in your AutoPi account"¶

The API key is valid but the vehicle profile endpoint returned no vehicles, so the config flow aborts rather than creating an entry with nothing to monitor.

1. Check the vehicle is actually registered and visible in the AutoPi dashboard.
2. Check the token's permissions include vehicle read access - a token scoped away from vehicles authenticates fine but sees nothing.

"AutoPi is already configured"¶

Only one config entry is created per AutoPi account setup. If you need a second account, add a second integration instance with its own API token rather than reusing the first.

"Unexpected error"¶

Anything not classified as a connection or auth failure falls through to this generic error. Enable debug logging and retry setup - the traceback in the log is the actual cause; the config flow only shows the generic message to the UI.

Authentication during normal operation¶

Integration prompts for reauthentication¶

When a request gets a 401 after setup, the coordinator logs Authentication failed: Invalid API key and Home Assistant raises a reauth flow rather than silently failing. This means the token was revoked, expired, or regenerated in the AutoPi dashboard after setup.

1. Follow the reauth prompt under Settings → Devices & Services and paste a fresh token.
2. Vehicle selection and all other options are preserved across reauth - you are only replacing the key.

"Integration stops updating after some time"¶

Usually one of:

1. Token expired or was regenerated - triggers the reauth flow above; check for a reauth notification before assuming something else is wrong.
2. AutoPi API unreachable - check Home Assistant's outbound connectivity and the AutoPi service status.
3. Check the diagnostic sensors (sensor.autopi_api_calls, sensor.autopi_failed_api_calls, sensor.autopi_api_success_rate) for a drop in success rate rather than guessing.

Entities missing or unavailable¶

A vehicle never appeared during setup¶

Vehicle selection only lists vehicles the AutoPi API returned for that account. If a vehicle is missing from the selection list:

• Confirm it's registered and online in the AutoPi dashboard.
• Confirm the API token has vehicle read access.

Entities show "unavailable"¶

Entity availability tracks the underlying vehicle/API state, not a fixed timeout. Check for:

• The vehicle hasn't reported data recently (device offline, ignition-gated reporting mode).
• The AutoPi API was unreachable on the last update - check sensor.autopi_api_success_rate and sensor.autopi_update_duration.
• A pending reauth (see above) - a stale token makes every entity unavailable at once, not just one vehicle's.

Only some data field sensors exist for a vehicle¶

Data field sensors (see Entity Reference) are created dynamically from the telemetry fields a vehicle actually reports. A vehicle without OBD wiring for a given PID, or an EV without HV battery telemetry, simply never creates the corresponding sensor - this is expected, not a bug.

GPS coordinates or speed look noisy while parked¶

GPS has inherent jitter and can report small non-zero speeds (0.1-0.5 m/s) or drifting latitude/longitude while stationary. Use a threshold above the noise floor in automations rather than treating any non-zero value as movement. Accelerometer X/Y/Z sensors specifically have a Suppress Accelerometer When Stationary option (enabled by default) that stops updating those three sensors while the vehicle is detected as stationary, to prevent this jitter from triggering automations.

Stale or zeroed values¶

This integration's data is a snapshot from the last successful poll, not a push feed - "stale" means the last_seen age on the underlying telemetry field is old, and "zeroed" is a specific optional behavior layered on top of that. Two different pages own the mechanics in detail:

• Auto-Zero Metrics (BETA) - what gets zeroed, when, and why.
• Auto-Zero Debug Logging - the log tags to read when auto-zero isn't doing what you expect.

Quick triage before diving into those pages:

A metric reads 0 unexpectedly¶

1. Check whether Auto-zero Metrics (BETA) is enabled in the integration options. If it's off, a sensor reading exactly 0 is real vehicle data, not auto-zero - go check the vehicle/AutoPi dashboard instead.
2. If it's on, only the metrics listed in Auto-Zero Metrics are eligible - engine OBD metrics, GPS-calculated fuel used, and the X/Y/Z accelerometer axes. Anything else reading 0 is not an auto-zero effect.
3. The threshold is fixed at 15 minutes and is not configurable. If the metric's last_seen is older than that, zeroing is expected behavior, not a fault.

A metric won't zero even though the vehicle has been off for a while¶

1. Confirm auto-zero is enabled and the metric is in the affected list (above).
2. Confirm your Update Interval is 1-10 minutes - the integration enforces this range, and the feature needs a short interval to catch staleness promptly. 5-10 minute intervals make auto-zero markedly less responsive; 1 minute is required for it to behave predictably.
3. Enable debug logging and look for [AUTO-ZERO EVAL] entries, which log the data age against the 15-minute threshold directly - see Auto-Zero Debug Logging.

A metric zeroes right after a Home Assistant restart even though it was fine before¶

This is the state-restoration path: a metric that was zeroed before restart stays zeroed until fresh data arrives, specifically to avoid briefly showing pre-restart stale data as if it were current. Look for RESTORED in the log - if a stored zero state is more than 24 hours old it is deliberately not restored (logged as SKIPPED) rather than persisting forever.

Polling interval and rate limits¶

Options won't save / "Update Interval" rejected¶

The Update Interval option only accepts 1-10 minutes. Values outside that range fail validation in the options flow.

Rate limited by the AutoPi API¶

A 429 from the AutoPi API is not retried automatically - it's logged as Rate limit exceeded and surfaces as a failed update immediately, so a burst of rate limiting shows up as a drop in sensor.autopi_api_success_rate right away rather than a delayed recovery. (Server errors and connection failures are retried - up to 3 attempts with a short linear backoff - but rate limiting is not one of those cases.) If you're hitting this often:

1. Increase Update Interval (fewer vehicles polled per minute).
2. Check sensor.autopi_failed_api_calls and sensor.autopi_api_success_rate to see whether failures are actually rate-limit related or something else (auth, connectivity).
3. Note the trade-off with Auto-Zero Metrics: a short interval is what auto-zero needs, and is also what drives up call volume - see API Optimization for the interval trade-offs.

Reading the logs¶

Enable debug logging in configuration.yaml:

logger:
  default: info
  logs:
    custom_components.autopi: debug
    custom_components.autopi.coordinator: debug
    custom_components.autopi.client: debug

The client logs the HTTP method and endpoint (not the full URL, to avoid leaking the base URL) and the response status for every request, and explicitly filters api_key/token out of any logged request parameters. It does not filter sensor values, so debug logs for position and telemetry sensors will contain the actual data - including GPS coordinates - while enabled. See Security before sharing debug logs publicly.