---
title: "Homepage Dashboard — Proxmox Widget Quirks and Common Failures"
aliases: [homepage-proxmox, homepage-widget, homepage-dashboard, homepage-config]
tags: [homepage, proxmox, homelab, dashboard, selfhosted, widgets]
sources:
  - "daily/2026-04-19.md"
created: 2026-04-19
updated: 2026-04-19
---

# Homepage Dashboard — Proxmox Widget Quirks and Common Failures

Homepage (gethomepage.dev) has several non-obvious failure modes when used with Proxmox. Version 0.10.9 introduced stricter requirements for the Proxmox widget that silently produce N/A values. Combined with LXC networking issues and Node.js SSL behavior, Homepage can appear completely broken when each individual issue is minor and fixable.

## Key Points

- **Homepage v0.10.9+ requires explicit `type: node|vm|lxc`** in the proxmox widget config — without it, the widget connects successfully but shows N/A for all metrics
- **`pnpm start` is the correct startup command**, not running the standalone server directly — the standalone server doesn't resolve widgets correctly
- **Duplicate `HOMEPAGE_ALLOWED_HOSTS`** across the main env file and a drop-in conf causes silent issues — deduplicate to one location
- **Node.js ignores Linux system trust store** — self-signed Proxmox certs require `NODE_TLS_REJECT_UNAUTHORIZED=0` in the systemd unit file, not a shell export
- **ARP cache in LXC** can cause all widget API calls to fail simultaneously — `ip neigh flush dev eth0` before other debugging

## Details

### Proxmox Widget Config (v0.10.9+)

The `type` field is mandatory. Without it, Homepage will authenticate with the Proxmox API, receive valid data, but fail to parse and display it:

```yaml
# services.yaml — Proxmox widget
- Proxmox:
    href: https://192.168.1.100:8006
    widget:
      type: proxmox
      url: https://192.168.1.100:8006
      username: root@pam!homepage
      password: "{{HOMEPAGE_VAR_PROXMOX_TOKEN}}"
      node: pve
      type: node          # REQUIRED — node, vm, or lxc
```

For listing VMs and LXCs separately, add multiple widget blocks — one with `type: node` for host stats, others with `type: vm` or `type: lxc` for individual containers.

The proxmox.yaml file (if used as a split config) must not be entirely commented out — check for `#` at the start of every line if metrics suddenly disappear.

### pnpm start vs Standalone Server

Homepage has two run modes: the development server (`pnpm dev`) and the production start (`pnpm start`). There is also a pre-built standalone server binary. The standalone server has known issues with widget resolution — it doesn't correctly resolve the widget API proxying logic. Always use `pnpm start` in production.

For a systemd service:
```ini
[Service]
WorkingDirectory=/opt/homepage
ExecStart=/usr/bin/pnpm start
Environment=NODE_TLS_REJECT_UNAUTHORIZED=0
```

### HOMEPAGE_ALLOWED_HOSTS Deduplication

If Homepage is configured with environment variables split across a main `.env` and a systemd drop-in (`/etc/systemd/system/homepage.service.d/env.conf`), duplicate keys cause the last value to win unpredictably:

```bash
# Check for duplicates
grep -r HOMEPAGE_ALLOWED_HOSTS /etc/systemd/system/homepage.service* ~/.config/homepage/

# Remove from drop-in if it's also in .env, or vice versa
```

### Diagnosis Order for Widget API Errors

When Homepage shows "API Error" on all custom widgets:

1. **Check ARP cache first** — `ip neigh show` inside the LXC; flush if stale entries
2. **Check SSL** — is the target using a self-signed cert? Add `NODE_TLS_REJECT_UNAUTHORIZED=0` to systemd unit
3. **Check Proxmox widget `type` field** — is it explicitly set?
4. **Check proxmox.yaml** — is it fully commented out?
5. **Check for duplicate env vars** — `grep HOMEPAGE_ALLOWED_HOSTS` across all config locations
6. **Restart after each change** — `systemctl restart homepage`

### Why Homepage Was Replaced with Dashy (2026-04-19)

After all the above fixes were applied, Homepage still had persistent API errors. The accumulated complexity — ARP cache issues, SSL workarounds, widget config requirements, duplicate env vars, pnpm vs standalone — led to a decision to replace Homepage with Dashy. Dashy has a simpler config model and does not require per-widget API integrations for the use case (bookmark-style dashboard with visual stats).

## Related Concepts

- [[wiki/concepts/nodejs-ssl-system-trust-store]] — why system trust store doesn't work and how to fix it in systemd
- [[wiki/concepts/lxc-arp-cache-api-failures]] — the root cause of widespread widget API errors
- [[wiki/concepts/tailscale-dns-homelab]] — DNS setup needed for the dashboard to be accessible on mobile
- [[wiki/homelab/_index]] — Proxmox and LXC infrastructure context

## Sources

- [[daily/2026-04-19.md]] — Multiple Homepage debugging sessions: ARP cache fix, SSL systemd fix, proxmox widget type field, pnpm vs standalone, duplicate env vars; ultimately abandoned Homepage for Dashy
