Troubleshooting

Symptoms an operator actually sees, and what to do. Error codes are in ../ERRORS.md.

Starting up

The black window closes immediately. Python is missing or the dependency install failed. Run run.bat from a command prompt so the window stays open and read the last few lines.

"Address already in use" / the page will not load. Another copy is already running, or something else holds port 5100. Close the other black window, or check with netstat -ano | findstr :5100.

The browser opens but the page is blank. Hard-refresh with Ctrl+F5. If it stays blank, the browser is too old — Diaco Studio needs WebGL2 and ES modules. Chrome or Edge from the last two years.

The owner console

Where is it? http://127.0.0.1:5001/ — a different port from the clinic application on purpose. It is not reachable from the clinic app and never was meant to be.

It asks me to create a password instead of entering one. Nobody has claimed the console yet. Whoever opens it first sets the password, so open it yourself before anyone else can.

Locked out after wrong passwords. Five failures locks the console for fifteen minutes. Wait; there is no bypass.

I forgot the console password. There is no recovery by design — that credential downloads the whole database. Restore the admin_auth row from a backup, or reinstall and restore the data.

A practitioner cannot sign in. Check the console's Practitioners list. An account showing deactivated has had its password cleared and cannot sign in until you reset it. If they never signed in successfully, reset the password and give them the new one directly.

Signing in to the clinic

It asks me to choose a password the first time. Working as intended. The password you were given is known to whoever created the account; replacing it is the first thing you do, and the old one stops working the moment you do.

"That is the password you were given." Choose a different one — the point is that it changes.

The demo

**The Demo button is not in the header.** It appears once you are signed in — the sample case is filed in a clinic, and in local mode there is no clinic to file it in.

"The demo data is already loaded." A demo is still open from last time. Press Demo to pick it back up, then End demo.

"This build does not include the sample scan." test-data/sample-scan.stl is missing from the install. Without it there is nothing to build the sample case from.

The bar lost its place. It lives in the browser, so a different browser or a private window starts over. The sample data is unaffected — press Demo and it picks up at step one.

Scans

"Cleanup & alignment done ✓" with kept_largest_of_N_components. The scan contained N separate pieces and the biggest was kept. Usually floating debris, sometimes a genuinely broken scan. Check the measurements against the patient before continuing.

Upload rejected: unsupported format. STL, OBJ, PLY only. Export again from the scanner.

The limb looks inside-out. You scanned a negative cast without ticking the box. Re-upload with This is a negative plaster cast ticked.

The measurements are wrong. Nothing downstream can fix this. Re-scan. Do not rectify your way out of a bad scan.

Socket build

"Generate" does nothing and jumps to Rectification. A socket is built from a saved rectified version. Go to step 3 and press Save rectified & next step, even if you changed nothing.

Warning: threemf_no_socket_profile_installed_bare_geometry_exported. No socket print profile is installed, so the 3MF carries geometry with no print settings. Owner console → Print profiles → install the project your print farm exported, named socket- something.

The print check says not_watertight. The socket did not close. Almost always a rectification that pushed material through the far wall, or a scan with a hole. Revert, check the limb, rebuild.

"Wall thickness — not measured". Same cause: an open mesh has no inside, so there is no wall to measure. The application says so rather than printing a number it cannot stand behind.

The measured wall is thinner than I asked for. Expected at the rim, where the rounding thins the wall by a few tenths. Far below the requested figure anywhere else means the rectification created a pinch — look at the heat map.

Insoles

FIT FAIL. Read the diagnostics panel: minimum thickness, wall angle, or topology. The usual cause is a parameter pushed past what the size can carry — reduce the arch height or the heel cup, or step the size up.

The gait scan is refused. The message says why: an unsafe path inside the archive, an absolute path, an encrypted member, or too much data. These checks are deliberate; do not work around them. Re-export the archive from the plate software.

The pair looks identical for every pathology. Change the pathology before generating — the preset resolves into parameters at generation time.

Batch build

"No patient folder here has both left and right STL files." The day folder must contain one subfolder per patient, each holding Left-Insole-1.STL and Right-Insole-1.STL.

"This folder already has a 3MF file." Protection against overwriting finished work. Tick Overwrite existing files only if you mean it.

The folder is on a network drive and cannot be seen. The application runs as the logged-in user. Map the drive for that user, or use a UNC path.

Printing

The print queue is empty but I approved a design. Approving files the design; Send to printer writes the project. They are separate on purpose — approval is clinical, queueing is production.

The printer does not pick jobs up. Check the folder shown at the top of the queue matches your farm's watch directory. Change it in the batch-build settings.

Data

Take a backup before every upgrade. Owner console → Download backup. It contains patient data; store it accordingly.

How do I remove the demo records? Press End demo in the demo bar. If the bar is not showing, press Demo in the header to bring it back, then end it. It removes exactly what it created.

Disk filling up. Every version keeps its mesh. Delete cases you no longer need from the patient view; the files go with them.

Automatic pricing (the slicer)

"Slice it for me" reports an error instead of numbers. Read the error — it is the slicer's own words, not ours. Two are common:

"Relative extruder addressing requires… Add G92 E0 to layer_gcode." OrcaSlicer has no printer configured on this machine, so it fell back to a default profile that will not slice. Open OrcaSlicer, pick your printer and filament, and save them as presets. Press Probe in the console afterwards.

"The slicer crashed (segmentation fault)." This build cannot slice a .3mf project from the command line — verified on 2026-08-30 against OrcaSlicer's own project export, so it is the build and not the file. Update OrcaSlicer, or keep pricing by hand.

Nothing happens / there is no Slice button. No slicer was found. Install OrcaSlicer, or set its path in the console under Settings → OrcaSlicer executable.

None of this stops you quoting. Slice the job in OrcaSlicer yourself, read filament used [g] and estimated printing time off the G-code, and type the two numbers into the pricing form. Every other figure on the quote is worked out from the clinic's own terms either way — the slicer only ever supplies those two.

Paying for a print order

"Pay by card" is greyed out. Working as intended for now. Card and SEPA go through Stripe, which needs a merchant account in the company's name; until that exists the button says so rather than failing after the clinic has typed their details. Wallet and bank transfer both work today.

Turning card payment on. Console → Settings → paste the Stripe secret key. Nothing else changes: the option stops being greyed out and starts working.

"Mark paid" pressed twice. It cannot charge twice. The second press answers "already settled" and moves no money; the ledger is checked for exactly one debit by the test suite.

A wallet order will not settle. The balance would go below the debt floor. Charge the wallet, or have the clinic pay on invoice instead — the quote shows both figures.