Troubleshooting

Troubleshooting

A growing list of common breakages and fixes. If your problem isn't here, open an issue with reproduction steps.

Setup / first run

npm ci fails with "Missing: @swc/helpers from lock file"

The Dockerfile uses node:20-alpine which ships npm 10.8.2; the package-lock.json was generated by a newer npm. Two fixes (the maintainer's repo bumps npm 11 in the Dockerfile already; this guidance applies if you're customizing):

# In webapp/docker/Dockerfile, deps stage:
RUN apk add --no-cache libc6-compat && npm install -g npm@11

Or relax npm ci to npm install --no-audit --no-fund (looser; lockfile drift becomes a warning, not an error).

setup.sh errors on macOS — "command not found: bash"

The script uses bash 4-isms (associative arrays, [ ... ]( ... .md)). macOS ships bash 3.2 by default. Install via Homebrew:

brew install bash

Then re-run with the new shell:

/usr/local/bin/bash ./setup.sh

Stack starts but webapp returns 404 on every URL

Most common cause: you ran docker compose up -d against the base compose file but you actually need the Traefik override loaded too (the base file has no Traefik labels). Either:

docker compose -f docker-compose.yml -f docker-compose.traefik.yml up -d

Or use the helper:

export COMPOSE_FILES="-f docker-compose.yml -f docker-compose.traefik.yml"
./start.sh up

If you're hitting Kinboard directly (no Traefik), check that WEBAPP_PORT in .env matches the URL you're using.

Kong returns 401 on every API call

kong.yml still has the placeholder JWTs (REPLACE_WITH_ANON_KEY / REPLACE_WITH_SERVICE_ROLE_KEY). After pasting your Supabase keys into .env, re-run setup.sh — it substitutes them into kong.yml automatically.

"Database is empty / can't load" on dashboard

Either:

• The DB volume bind path changed when you upgraded to the templated docker-compose.yml. Check DATA_DIR in .env matches your existing data path. (For an existing prod deploy, use webapp/docker/migrate-prod.sh to add the variable safely.)
• Cookies are stale. Clear cookies for the site (specifically the family-store cookie) and rejoin via /join.

Real-time sync

Edits on one device don't appear on the other

1. Check that both devices are connected to the same family — Settings → top of page → join code matches
2. Open the browser dev tools → Network → WS tab. You should see an open WebSocket to /realtime/v1/websocket. If it's closed/erroring, the issue is reaching the realtime container — check kinboard-realtime health
3. If the WS is open but no messages arrive when you edit on the other device, the table may not be in the realtime publication. See Database-Schema → Realtime publication.

Storage container is "unhealthy"

Cosmetic. Supabase Storage's healthcheck is over-aggressive upstream and frequently false-positives. As long as recipe-image uploads work, you can ignore it. Issue tracked at https://github.com/supabase/storage/issues.

Integrations

Google Calendar — connect popup says "redirect_uri_mismatch"

The redirect URI in Google Cloud Console doesn't match what Kinboard sends. Add:

• http://localhost:3001/api/google/callback (dev)
• https://<your-domain>/api/google/callback (prod)

…to Authorized redirect URIs in your OAuth client.

Home Assistant — "Connection failed" but the URL works in a browser

• Token has expired (long-lived tokens last 10 years, but if the user was deleted in HA, the token's gone too)
• Kinboard runs HTTPS but HA URL is HTTP (mixed content blocked). Either upgrade HA to HTTPS or run Kinboard on HTTP.
• cors_allowed_origins in HA config restricts the origin list. Add your Kinboard origin.

Bring! — "Login failed"

Bring! rate-limits credential checks. Wait 5 minutes between attempts. If you've correctly typed your email + password three times and it's still rejected, sign out + back in via the Bring! mobile app to confirm the credentials work; then retry.

Cameras — black tile, no stream

WebRTC ICE failure. Check:

• WEBRTC_LAN_IP in .env matches your server's LAN IP
• UDP 8555 is forwarded through your firewall
• go2rtc.yaml substitutions (CAMERA_USER, CAMERA_PASS, etc.) are filled in

Cameras — auth dialog pops in browser

The stream URL has credentials but the browser doesn't accept them. Use the Authentication section in /settings/cameras to set username + password + Digest type. Kinboard's /api/cameras proxy will handle the auth server-side.

Notifications

Test notification doesn't arrive

1. Check the device is subscribed (Settings → Notifications, push toggle is on)
2. Check VAPID keys are set in .env (VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY)
3. Some browsers block notifications when the page isn't HTTPS. Run Kinboard over HTTPS for production.

iOS device — push button toggles but nothing arrives

iOS only delivers web push to installed PWAs. Tap Share → Add to Home Screen, then open from the home-screen icon.

Kiosk

Edge --kiosk doesn't auto-launch on boot

Open Task Scheduler → KioskLauncher task → check Last run result. Common results:

• 0x41306 — task failed because user wasn't logged on. Confirm AutoLogon is set.
• 0x1 — script returned nonzero. Check C:\kiosk.log for what failed.

On-screen keyboard doesn't appear

EnableDesktopModeAutoInvoke registry key not set, or TabTip.exe isn't running. Re-run kiosk-launcher.bat manually:

C:\kiosk-launcher.bat

Verify TabTip is in Task Manager. If not, it failed to start — likely Windows blocked it. Run gpedit.msc → Computer Configuration → Administrative Templates → Windows Components → Tablet PC → make sure "Touch Keyboard" isn't disabled.

Presence sensor reads "no data" / "watchdog reconnecting"

• Serial cable physically loose
• USB-UART driver missing (CH340 needs a manual driver download from wch.cn; FTDI is built-in)
• Wrong baud rate (LD2410 default is 256000, not 115200)

Check C:\presence-sensor.log — the watchdog message tells you exactly when it last got data.

Deployment

./deploy.sh step 3 fails on Docker build

The Docker build step does next build which runs tsc --noEmit. If you have type errors locally that lint didn't catch (the project uses lint-only as default policy), they surface here.

To preempt this: run npx tsc --noEmit from webapp/ before deploying.

migrate-prod.sh says ".env not found"

Run from the webapp/docker/ directory of the live deploy, not from your dev machine. The script operates on the .env it sits next to.

After deploy, all routes 404

If deploy.sh recreated the webapp container with only the base compose file (no Traefik override), Traefik dropped the route. Run migrate-prod.sh on the host to render the Traefik override, then restart with all overlays:

cd webapp/docker
./migrate-prod.sh
docker compose -f docker-compose.yml -f docker-compose.traefik.yml -f docker-compose.override.yml up -d --no-deps webapp

Performance

Dashboard slow to load on the kiosk

• First load fetches a lot of state (events for the next month, todos, shopping items, weather, HA entity states, etc.). Subsequent loads are cached. If chronically slow, profile via the browser dev tools.
• The Mele 4C runs Kinboard fine. Cheaper boxes (Raspberry Pi 4 with browser kiosk) may struggle — the bottleneck is Chromium's React runtime, not the network.

Edge eats RAM on the kiosk

Set Edge to start with limited tab discarding via Group Policy:

HKLM\SOFTWARE\Policies\Microsoft\Edge
  AutomaticFullscreenAllowedForUrls = ["[*.]your-kinboard-domain"]  (REG_MULTI_SZ)

Or simpler: schedule a daily Edge restart at 03:00 via a separate scheduled task that kills Edge and re-launches it.

Database / data

"Settings lost after deploy"

Almost always a cookie issue, not actual data loss. Verify the family-store cookie still points at the right family ID:

// browser console
document.cookie

If the cookie is missing, you'll be on /join and creating a new family looks like data loss. The original family's data is still in the DB; rejoin with the original code.

pg_dump errors with permission denied

The Postgres container runs as user postgres. pg_dump needs to run inside the container or with credentials:

docker exec -t kinboard-db pg_dump -U postgres -F c postgres > /backups/kinboard.pgdump

When all else fails

# Capture the state for an issue report
cd webapp/docker
./start.sh status > /tmp/kinboard-status.txt
docker logs kinboard-webapp --tail 200 > /tmp/kinboard-webapp.log
docker logs kinboard-realtime --tail 100 > /tmp/kinboard-realtime.log

# File an issue with all three attached

Open a bug report on GitHub.