Troubleshooting
The phone cannot open the page
The certificate is self-signed. iOS: Show Details → visit this website; Android: Advanced → proceed. Both devices must be on the same network; the banner prints the address it certified. If the address changed (new wifi), delete .cache/lan-cert.pem and lan-key.pem and restart to certify the new one.
The phone sees a login page
It needs the access token: scan the QR code from the startup banner (tail ~/Library/Logs/soldermask.log or the terminal), or type the token printed there. See Access control.
"Chat needs a model" / composer disabled
No backend credentials. Export GEMINI_API_KEY (or GOOGLE_API_KEY), or SOLDERMASK_BACKEND=claude with ANTHROPIC_API_KEY, and restart. /about says which it found. You can import a design.json without any model.
The Route pill says "not run"
No working Java or no router jar. /about shows the Java it found; the command line prints the reason (no Java runtime found (freerouting needs Java 25+) or freerouting jar not found at …). On macOS, /usr/bin/java is a stub that only prints an advert and is correctly ignored; install brew install openjdk. Put freerouting-2.4.1.jar in vendor/.
"n unrouted"
Freerouting gave up on some nets. Common causes: a part with many pins on a small board, or a dense header. Ask for a larger board, fewer parts, or a different arrangement; the board is saved either way and the unrouted nets are listed on the command line.
Parts missing, "no JLCPCB part exists for …"
The model's search term found nothing orderable in that package. Rephrase with a manufacturer part number or a plainer description, or change the package. See the query ladder. If every part failed at once, the parts index was unreachable — the gap says could not reach JLCPCB … this is an outage here — and the parts cache will serve stale data for a day.
Tilt does nothing
Tilt needs a secure origin: use the HTTPS address, not --http, and grant the motion permission when the phone asks (iOS asks once, from the button).
The 3D view shows boxes instead of parts
That version was built before models were part of a build, or the part has no vendor model (a note says so). python tools/backfill_models.py <project> adds models to old versions.
"already building"
One build per project at a time. Wait for it, or watch it: the workbench picks a running build up on reload.
A build failed with a pipeline error
The reply names the stage and exception; the server log (--log-file, or stderr) has the traceback under soldermask.jobs. The project is untouched: a failed build writes no version.
The About page says "uncommitted changes" or "no tag"
Informational. It is a git checkout with local edits, or a version that has not been released. See Versioning and releases.
Everything at once: a health check
curl -sk https://localhost:8443/api/health # {"ok": true, ...}
curl -sk https://localhost:8443/api/app | jq # chat, router, data_dir
soldermask version # what is installed
python tests/run.py # the whole suite