Troubleshooting¶
"Entiteit niet gevonden" (Entity not found)¶
The card cannot find one or more sensor entities.
Causes and solutions:
- The parcel integration is not installed — install the integration for your carrier (see Installation) and configure your account or tracking number.
- The
userfield does not match your sensor prefix — check the actual sensor name in Developer Tools → States and adjustuseraccordingly. - The sensors have no username prefix — leave
userempty (user: ""). - 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/*orHummelsTech/*.
No parcels shown¶
The card loads but the parcel list is empty.
Causes and solutions:
days_backis too short — increase the value to show older delivered parcels.- The integration has not yet received data from the carrier — wait for the next update cycle or trigger a manual refresh.
- 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).
- 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:
show_deliveredis set tofalse— enable it in the card options.- The parcels are older than
days_back— increase the value. - Using an older
ha-postnlversion —ha-postnl≥ 4.0.0 is required for thepostnlcarrier type.
Sent parcels not visible¶
The Sent tab is empty, or missing entirely.
Causes and solutions:
show_sentis set tofalse— enable it.- 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.
- The
entity_outgoingsensor 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:
show_lettersis set tofalse— enable it.- The carrier type is not PostNL — only
postnlsupports letters. - The
entity_letterssensor 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:
- ha-postnl has not yet downloaded the images — images are fetched asynchronously and may take a few minutes after the letter data appears.
- 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. - 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:
- The control doesn't appear at all — it only shows when at least one configured carrier's integration has a
track_parcelservice ("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. show_add_parcel: falseis set — remove it or set totrue.- Submitting a tracking number does nothing / errors — the control calls the integration's own
track_parcelservice 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. - 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:
- 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.
- 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-closedicon 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:
show_animationis set tofalse— enable it.- No parcel is selected — click a parcel in the list to trigger the animation.
Card shows blank / white screen¶
Causes and solutions:
- The JavaScript file is not loaded — verify the resource is added in Settings → Dashboards → Resources and the path is correct.
- A JavaScript error occurred — open the browser console (F12) and check for errors. Report any errors on the issue tracker.
- Clear your browser cache (Ctrl+Shift+R) and reload Home Assistant.