soldermaskdocs

Troubleshooting

Each section below starts from what you see, then says why it happens and what to do.

The phone cannot open the page

The certificate is self-signed, so the phone warns about it.

  • iOS: tap Show Details, then visit this website.
  • Android: tap Advanced, then proceed.

Both devices must be on the same network. The startup banner prints the address it certified. If the address changed, for example on new wifi, delete lan-cert.pem and lan-key.pem from the cache directory and restart. In a checkout the cache is .cache/, and soldermask setup --check prints where it is.

The certificate is made for 365 days and kept until you delete it. After that, the phone warns that it has expired. Delete the same two files and restart.

The phone sees a login page

It needs the access token. Scan the QR code from the startup banner, or type the token printed there. The banner is in the terminal, or in ~/Library/Logs/soldermask.log under launchd. See Access control.

"Chat needs a model", or the composer is disabled

The server has no model credentials. Set one of these and restart:

BackendSet
Claude Code (the default)Install Claude Code, then run claude once and log in with claude.ai
GeminiSOLDERMASK_BACKEND=gemini, plus GEMINI_API_KEY or GOOGLE_API_KEY
ClaudeSOLDERMASK_BACKEND=claude, plus ANTHROPIC_API_KEY or a login with ant auth login

A tool install also needs the backend's SDK for Gemini or Claude. Install with --with google-genai or --with anthropic, as in Install. Without it, /about says install google-genai or install anthropic.

/about says which credentials it found. You can still import a design.json without any model.

The Route check says "stopped"

The router did not finish, so the board is placed and not routed, and the verdict is NO-GO. Lightcycle goes first. When it cannot run, the A* router routes the board if it is installed. The gaps say which router ran, and why the other did not.

With neither router, the gaps read no router is installed: the board is placed and not routed (soldermask setup). The projects page says router not ready: boards will save unrouted.

MessageFix
Lightcycle is not installed (soldermask setup)Run soldermask setup.
Lightcycle <old> is installed and this soldermask needs <new>An upgrade moved the pinned version. Run soldermask setup, which installs the pinned one.
no Lightcycle wheel could be downloaded for this machine, from soldermask setupRun gh auth login, or set GH_TOKEN, with an account that can read soldermask-org/lightcycle. Or install Rust from rustup.rs so setup can build it.
Lightcycle did not return in 600 s and was stoppedSee A route stopped after 600 seconds.
KiCadRoutingTools not at … or the Rust core is not builtRun soldermask setup --astar. This is only needed for the A* router.

/about shows which router this machine will use.

A route stopped after 600 seconds

The gaps read Lightcycle did not return in 600 s and was stopped: the route is left undone rather than the build held on it. Lightcycle routes each whole board in a process of its own, and stops it at SOLDERMASK_ROUTER_WALL_S seconds. The build goes on without that route.

  • If the A* router is installed, it routes the board instead, and the gaps say so.
  • Otherwise the board is saved unrouted. Try Place again for a new arrangement.

The verdict says UNJUDGED

Nothing that ran failed, but a check the verdict needs did not run. Click the poll to see which.

The verdict saysWhyFix
no DRC judged the copperkicad-cli is not installed, or it failed. The command line prints kicad-cli not installed -- no DRC, render or GLB.Install KiCad and check soldermask setup --check prints a kicad path. Then rebuild, or run soldermask projects rejudge for saved versions.
the electrical check (ERC) did not run on this boardThe board was read from a board file, such as a .kicad_pcb, so no ERC ran.None. A board read from a file stays UNJUDGED on this check.

No pin was checked against a KiCad symbol

The gaps read the KiCad symbol library is not on this machine. The board still builds, from each vendor's own symbols alone. Run soldermask setup, which fetches the library, then rebuild.

"n unrouted"

The router could not reach every pin. A part with many pins on a small board, or a dense header, is the usual cause.

  • Ask for a larger board, fewer parts, or a different arrangement.
  • In the workbench, try Place again for a new arrangement.

The board is saved either way, and the command line lists the unrouted nets.

Parts missing: "no JLCPCB part exists for …"

The model's search term found nothing orderable in that package.

  • Rephrase it 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 service was unreachable. The gap then says could not reach JLCPCB … this is an outage here. Cached answers are reused for up to a day.

Tilt does nothing

Tilt needs a secure origin. Use the HTTPS address, not --http. Allow the motion permission when the phone asks; iOS asks once, from the button.

The 3D view shows boxes instead of parts

Either the version was built before 3D models were part of a build, or the part has no vendor model and a note says so. To add models to old versions, run this from a checkout:

.venv/bin/python tools/backfill_models.py <project>

"already building"

Each project builds one board at a time. Wait for the build to finish. The workbench picks up a running build when you reload.

A build failed with a pipeline error

The reply names the stage and the exception. The server log has the traceback under soldermask.jobs, in stderr or the --log-file. The project is untouched, because a failed build writes no version.

The About page says "tree dirty" or "tag none"

This is information, not an error. tree dirty means the server runs from a git checkout with local edits. tag none means its version has not been released. See Versioning and releases.

Check everything at once

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
soldermask setup --check                         # routers, kicad-cli, catalogue
.venv/bin/python tests/run.py                    # the whole suite, from a checkout

On this page