Troubleshooting¶

Start with the path you use: headless Python, desktop, or cloud. For beta help, contact beta@leapfield.ai.

No local solver¶

Installing the Python SDK does not install the engine. Invited testers receive an archive and checksum separately. Follow the headless install. The installer CLI requires photonhub 0.1.4 or later; with an older SDK, upgrade or use that guide's manual route.

import photonhub as ph
print(ph.__version__, ph.SCHEMA_VERSION)
print(ph.find_solver())

find_solver() chooses an explicit solver_path, then PHOTONHUB_SOLVER, then a recorded install/link, PATH, and an eligible source build. An invalid explicit path or environment override is an error. Correct it instead of expecting discovery to skip it. A recorded solver that was moved must be installed or linked again.

With the installer CLI, photonhub which-solver --info names the selection and its build. On the manual route, run the selected binary's info command. Keep the unpacked solver beside its bundled runtime. A desktop-bundled solver requires a signed-in Workbench; use the headless archive for scripts.

Errors¶

What you see	Meaning	Next step
`ValueError`, including model validation errors	Construction, runnable preflight or invalid arguments failed before execution.	Read the field and message. Add a source, fix geometry or monitor placement, or enlarge the usable interior.
`SolverRunError`	Solver discovery, execution, divergence, cancellation or unreadable local outputs.	Check the selected engine, spec and recorded solver message. Keep the output directory.
Local `timeout=` expires	The local runner stops the subprocess and raises `SolverRunError`.	Check size, run duration and logs before increasing the limit.
`CloudError`	Configuration, authentication, service, transport or result transfer failed.	Read `.status_code` and `.body`. If `.job_id` is present, resume that job.
`CloudJobTimeout`	The client stopped waiting; the cloud job continues and can still bill.	Save the id and resume or request cancellation.
Raw filesystem, callback, HTTP timeout or I/O error	Some errors originate outside the normalized runner paths.	Keep the traceback. Check the output path or callback and reconcile cloud history if submission may have occurred.

A geometry-only simulation is valid for plotting or mode solving. Running it without sources fails preflight with ValueError. The SDK also checks resolved grid and stability rules; the selected engine remains authoritative.

After an ambiguous cloud submission failure, check history before submitting again. A second submission can create a second paid job. A cancellation request is not proof of cancellation. Check the service response and job status.

Results differ after reload or between engines¶

Keep the entire result directory, including sim.json, client.json when present, the manifest and monitor files. Wire simulation JSON alone does not retain declarative ports or the user-frame origin. Keep the construction script to edit or reproduce those scenes. See Preserving state.

A common schema does not promise identical numbers. Compare engine revision, mesh, subpixel settings, materials, boundaries, precision and run controls. Use data.provenance to identify the engine. The cloud engine may lag source; see Known limitations.

Desktop recovery¶

Registration, sign-in and launch validation require Internet access. The beta has no self-service password recovery. Contact support without sending a password, invitation code, API key or session material.

Recovery restores applied edits and run history. Text not applied in an editor can be lost on restart. Keep portable solver inputs and backups before an upgrade. Older app versions may not read newer recovery archives.

Help → Create Diagnostic Bundle creates a local summary. Review it before sharing. Report a bug sends a report to the beta service and can include a screenshot. Review the preview and disable the screenshot when it contains private device or result information.

What to include in a support request¶

Send the SDK/app version, operating system and architecture, selected engine's info output or result provenance, exact error and traceback, and the steps that reproduced it. If possible, use a small scene that removes private design data. State whether the failure happened locally, during submission, while waiting or during download. Keep cloud job ids privately for reconciliation. Do not include credentials or private geometry in email or screenshots.