Homarr — SQLite Integration Cleanup After Major Upgrades

When Homarr removes a widget integration kind in a major update, existing entries with that kind remain in the SQLite database. On next load, the dashboard UI tries to read the name property of the unknown integration type, finds undefined, and crashes with TypeError: Cannot read properties of undefined (reading 'name'). The /manage/integrations page becomes inaccessible until the stale row is removed directly from SQLite.

Key Points

Root cause: Homarr stores integrations in an integration SQLite table with a kind column; when a kind is removed from the codebase, the row persists — the app crashes when it tries to look up the removed kind's metadata
Symptom: TypeError: Cannot read properties of undefined (reading 'name') in the browser console; /manage/integrations page crashes on load
Fix: Delete the stale row from SQLite directly — DELETE FROM integration WHERE kind = 'dockerContainers';
Known removed kind (April 2026 update): dockerContainers — was removed when Homarr redesigned its Docker integration; entries with this kind crash the integrations page
Safe operation: deleting the stale integration row only removes Homarr's internal reference to the integration widget; the Docker service itself is unaffected

Details

Why This Happens

Homarr's integrations system maps each integration widget to a kind string (e.g., dockerContainers, proxmox, jellyfin). When Homarr updates its integration registry (renaming or removing a kind), existing SQLite rows with the old kind become orphaned. The dashboard's integration page iterates over all rows and looks up each kind in the registry — a missing kind returns undefined, and the subsequent .name access throws.

The crash happens at page load, not lazily — meaning every visit to /manage/integrations fails, making it impossible to remove the bad integration through the UI.

Finding and Removing Stale Integrations

Homarr stores its database in the container at /data/db.sqlite (exact path may vary by install method):

# Enter the Homarr container or LXC
# For Docker:
docker exec -it homarr sh

# For LXC-based install, SSH into the container directly

# Open the database
sqlite3 /data/db.sqlite

# List all integration kinds to find the unknown one
SELECT id, name, kind FROM integration;

# Remove the stale row (example: dockerContainers kind)
DELETE FROM integration WHERE kind = 'dockerContainers';

# Verify
SELECT COUNT(*) FROM integration WHERE kind = 'dockerContainers';
# Should return 0

.quit

After removing the row, restart Homarr and the integrations page will load normally.

Diagnosing Which Kind Is Breaking

If the error message alone isn't clear, check the browser DevTools console for the full stack trace — it typically includes the kind value being processed when the crash occurs. Alternatively, query the database before deleting:

-- See what kinds exist vs what's in the app's registry
SELECT DISTINCT kind FROM integration ORDER BY kind;

Cross-reference the listed kinds against the current Homarr version's supported integration types. Any kind not present in the current release is a candidate for removal.

Post-Upgrade Checklist for Homarr

After any major Homarr version bump:

Check release notes for removed or renamed integration kinds
Open /manage/integrations — if it crashes, open DevTools console for the error
Query SELECT DISTINCT kind FROM integration; to find all stored kinds
Remove rows for any kind that no longer exists in the current version
Restart Homarr

This is a one-time fix per removed kind — Homarr does not provide automatic migration for removed integration types.

Docker DNS Issue (Same Session)

When the dockerContainers integration was working, Homarr also had a related issue: ping checks for internal services (e.g., Jellyfin) failed because Homarr's Docker container was using the router (192.168.1.1) as DNS instead of AdGuard Home (192.168.1.225). Internal domains like jellyfin.ai-impress.com only resolve via AdGuard. The fix: add explicit DNS to the Homarr docker-compose.yml. See wiki/concepts/docker-lxc-dns-configuration.

wiki/concepts/docker-lxc-dns-configuration — Docker containers in LXC/Proxmox need explicit internal DNS for homelab domains to resolve
wiki/concepts/homarr-proxmox-integration — Homarr Proxmox integration cert trust and general Homarr setup
wiki/concepts/proxmox-container-502-misdiagnosis — similar pattern of diagnosing before taking destructive action
wiki/homelab/_index — homelab dashboard and infrastructure context

Sources

daily/2026-04-28.md — Homarr /manage/integrations crashed with TypeError: Cannot read properties of undefined (reading 'name'); root cause was stale dockerContainers kind in SQLite from April 2026 Homarr update; fixed by DELETE FROM integration WHERE kind = 'dockerContainers'

5.3 KiB Raw Blame History