Troubleshooting

Troubleshooting

"Server not reachable" / cannot save

• Is the API up? systemctl status roomcad → systemctl restart roomcad.
• It binds 127.0.0.1:8078 only, so the proxy must forward /api/* to it.
• Running locally? The API is a separate process — start server.py as well as serve.sh.

The API will not start at all

It runs as the unprivileged roomcadapp user in a sandbox, so the usual cause is ownership of the data rather than a code fault. journalctl -u roomcad -n 30 will say which.

# It must own the database, the WAL sidecars SQLite creates beside it, and the
# directory they live in. The legacy .rcad directory too: the one-shot migration
# reads each file and then removes it, so a root-owned one is an unhandled
# PermissionError at boot.
useradd --system --no-create-home --shell /usr/sbin/nologin roomcadapp
install -d -o roomcadapp -g roomcadapp -m 755 /var/roomcad
chown roomcadapp:roomcadapp /var/roomcad/rooms.db /var/roomcad/rooms.db-wal /var/roomcad/rooms.db-shm
chown -R roomcadapp:roomcadapp /var/roomcad/rooms
systemctl restart roomcad

If it started failing right after a unit change, check the unit itself with systemd-analyze verify /etc/systemd/system/roomcad.service. ProtectSystem=strict makes the whole filesystem read-only, so the database's tree must appear in ReadWritePaths.

The login form keeps coming back

The password comes from ROOMCAD_PASSWORD in /var/roomcad/roomcad.env (mode 600, loaded by the systemd unit). If the file is missing the service still starts but logins fail closed:

printf 'ROOMCAD_PASSWORD=your-password\n' > /var/roomcad/roomcad.env
chmod 600 /var/roomcad/roomcad.env
systemctl restart roomcad

journalctl -u roomcad prints a warning at boot when it is unset.

Live updates do not arrive

Something is buffering the event stream.

• Caddy: the reverse_proxy block needs flush_interval -1.

• Caddy: encode gzip must be on the static handle, not at site level — at site level it also wraps /api/*, which is this stream.

• Check it directly — this should print an event immediately, not on close:

  curl -sN -b jar.txt https://your-host/api/watch/ternak_room1

"Join Live" never appears

It needs both: another browser session active in the last 30 seconds, and a design that came from the server. Save first, then wait ~3 s for the next presence poll. See Live Collaboration.

Light leaks along wall, floor or ceiling edges

Fixed in v2.9. If you see it again on an older build, the cause is one of two things, both covered by tests/plan-seal.test.mjs:

• a negative shadow bias (POINT_SHADOW_BIAS / sun.shadow.bias) — it makes every surface test as closer to the light than it is, and the error grows with the square of the distance;
• a wall join seal shorter than half the wall thickness, which leaves a real full-height notch of open air at each corner.

Run node tests/plan-seal.test.mjs; it fails on both.

Caddy reload fails with "permission denied"

scp uploads with mode 600, and each Caddy refuses a config it cannot read. The two files have different owners:

# RoomCAD's own Caddyfile
chmod 640 /var/roomcad/caddy/Caddyfile && chown root:roomcadweb /var/roomcad/caddy/Caddyfile
systemctl reload roomcad-caddy

# RoomCAD's route in the master
chmod 644 /var/caddy/projects/roomcad.caddy && chown caddy:caddy /var/caddy/projects/roomcad.caddy
/usr/bin/caddy validate --config /var/caddy/Caddyfile --adapter caddyfile && systemctl reload caddy

Always validate the master's config before reloading it: an invalid route there takes down every other project on the host, not just this one.

Cannot walk through a doorway

Doors are open by default; a closed one blocks the gap. Double-click it in 2D, or right-click it in 3D.

Furniture will not go where I want

It may sit flush against a wall (0 cm) but never overlap a wall or another item. Green means it fits, red means it does not — rotate with R or nudge with the arrow keys.

The 3D view is black, or will not start

• It needs WebGPU. Use a current Chrome, Edge or Safari Technology Preview; check chrome://gpu.
• Black but working? You may be in placed-lights-only mode at night. Press L for daylight, or set Time of day to around 12.

The 3D view is slow

Each ceiling light that casts shadows costs a full cube shadow map, and only the first 16 get one. Remove a few lights, or drop the browser zoom.

An old version of the app keeps loading

The deploy uses rsync --delete, so the server is correct — it is the browser cache. Hard-reload (⇧⌘R). The footer shows the running version; compare it with roomcad/web/version.js.