Skip to content

Troubleshooting

"Entiteit niet gevonden" (Entity not found)

The card cannot find one or more sensor entities.

Causes and solutions:

  1. The parcel integration is not installed — install the integration for your carrier (see Installation) and configure your account or tracking number.
  2. The user field does not match your sensor prefix — check the actual sensor name in Developer Tools → States and adjust user accordingly.
  3. The sensors have no username prefix — leave user empty (user: "").
  4. The editor's "integration not found" link points at the wrong repo — this was fixed to point at the ha-parcel-integrations org; update the card if you still see links to peternijssen/* or HummelsTech/*.

No parcels shown

The card loads but the parcel list is empty.

Causes and solutions:

  1. days_back is too short — increase the value to show older delivered parcels.
  2. The integration has not yet received data from the carrier — wait for the next update cycle or trigger a manual refresh.
  3. The sensor exists but has no attributes — verify the integration is authenticated (or, for account-less carriers, that at least one parcel has been registered).
  4. For tracking-code carriers ("Add parcel from card" in the Carrier types table) — nothing has been tracked yet. Use the "Add parcel" control, or the integration's own Configure dialog, to register a tracking number.

Delivered parcels not visible

Delivered parcels do not appear in the Delivered tab.

Causes and solutions:

  1. show_delivered is set to false — enable it in the card options.
  2. The parcels are older than days_back — increase the value.
  3. Using an older ha-postnl version — ha-postnl ≥ 4.0.0 is required for the postnl carrier type.

Sent parcels not visible

The Sent tab is empty, or missing entirely.

Causes and solutions:

  1. show_sent is set to false — enable it.
  2. The carrier has no Sent tab at all — its integration has no outgoing-parcels sensor. This is expected, not a bug; the Carrier types table shows which carriers have one.
  3. The entity_outgoing sensor is not configured and cannot be derived automatically — verify the sensor exists in Developer Tools and add a manual override if needed.

Letters tab not visible or empty

The Post tab does not appear or shows no letters.

Causes and solutions:

  1. show_letters is set to false — enable it.
  2. The carrier type is not PostNL — only postnl supports letters.
  3. The entity_letters sensor does not exist — the letters sensor is created by ha-postnl when your account has letterbox mail. Verify it exists in Developer Tools.

Letter images not showing

Letters appear but no scan images are displayed.

Causes and solutions:

  1. ha-postnl has not yet downloaded the images — images are fetched asynchronously and may take a few minutes after the letter data appears.
  2. The letter only has a placeholder image — ha-postnl v4.x creates a placeholder image.* entity before the real scan is available. The card automatically skips placeholder entities; when the real image is available it will appear automatically.
  3. The image entity is unavailable — the scan has not been received yet. Check the entity state in Developer Tools.

"Add parcel" is missing or fails

Causes and solutions:

  1. The control doesn't appear at all — it only shows when at least one configured carrier's integration has a track_parcel service ("Add parcel from card" in the Carrier types table). Account-based integrations without one — PostNL, DHL NL, DPD, Vinted Go — don't support it; see Add parcel support for why.
  2. show_add_parcel: false is set — remove it or set to true.
  3. Submitting a tracking number does nothing / errors — the control calls the integration's own track_parcel service directly. Check Developer Tools → Actions to confirm that service exists for your carrier's integration (e.g. gls.track_parcel), and check the integration's own logs for the actual failure reason (invalid tracking number, carrier API error, etc.) — the card only relays the call, it doesn't validate tracking numbers itself.
  4. For GLS/Trunkrs specifically — the parcel may land on the wrong hub if user (the postal code) isn't set correctly on that carrier entry, since it's passed along automatically with the service call.

Carrier overview popup shows the wrong icon or colour

Causes and solutions:

  1. If a carrier currently has zero parcels in every tab, the popup previously fell back to a generic icon and colour instead of the carrier's configured branding — fixed in v1.5.0b3. Update to the latest version.
  2. PHU coverage depends on both the carrier and your installed custom-brand-icons version. The mapping was checked against published release 2026.10.3; see PHU carrier icons. SVG scenes fall back to the carrier's existing logo when an icon is unavailable, and still work without PHU installed. On Home Assistant 2026.3+ carriers without their own card artwork show the integration's own brand icon; the browser console then shows one 404 per carrier whose integration ships none, which is harmless. A generic mdi:package-variant-closed icon outside the scenes is expected for unmapped carriers.

Animation not showing

The van animation does not appear when a parcel is selected.

Causes and solutions:

  1. show_animation is set to false — enable it.
  2. No parcel is selected — click a parcel in the list to trigger the animation.

Card shows blank / white screen

Causes and solutions:

  1. The JavaScript file is not loaded — verify the resource is added in Settings → Dashboards → Resources and the path is correct.
  2. A JavaScript error occurred — open the browser console (F12) and check for errors. Report any errors on the issue tracker.
  3. Clear your browser cache (Ctrl+Shift+R) and reload Home Assistant.