Troubleshooting

Use the Python environment that runs vibe-sketch for diagnostics and optional package installation. For a source checkout, activate .venv first. Start with vibe-sketch --version and retain the exact error message; the installation guide covers setup and updates.

Startup and the browser

Symptom	What to check
vibe-sketch is not found	Activate the environment or run .venv/bin/vibe-sketch from the checkout.
The browser cannot connect	Use the address printed by serve; the default port may already be occupied, causing selection of another port. Keep the server process running.
The API works but the editor is missing	Build the source browser bundle with cd web && npm ci && npm run build, then restart the server. A release wheel includes its bundle.
Drawing controls remain disabled	Wait for the initial document to load. If startup reports an error, correct that error and reload; see quickstart.
The source desktop command cannot find Electron	Use the source checkout’s installed command. vibe-sketch desktop checks and installs its reviewed runtime; a wheel alone does not include the source shell.
A source update refuses to proceed	Check for local changes or a diverged branch. Preserve your work before updating; use --skip-git only to reinstall the current tree.

For packaged-app startup, Python selection, native file dialogs and updates, use the desktop manual.

Imports, names and geometry

An import warning can mean the structure needs checking even when the drawing appears. Compare connectivity, stereochemistry, charge and multiplicity with the source. QVF and XYZ imports may perceive bonds from coordinates; periodic structures are refused. See file formats.

A missing or unverified name does not by itself mean that the drawing is invalid. Naming is optional and its vocabulary is limited. A suggested name is verified only when its round trip matches the structure, including stereo. See names for confidence and installation guidance.

If 3D generation fails, inspect the per-species warning rather than assuming that every species was embedded. Existing geometries are kept by default; use Redo or embed --replace when you intend to regenerate them. Generated conformers are starting geometries, not evidence of a converged quantum-chemistry calculation. The geometry tutorial explains the checks and force-field fallbacks.

Saving and exporting

A refusal to overwrite a QVF result protects content the sketcher cannot reproduce, including calculation payloads. Save the edited sketch to a new QVF or VSK destination. Importing a result does not preserve the original archive’s complete contents.

Keep a QVF or VSK master when exporting figures or exchange formats. SVG and PNG are figures, and formats such as MOL or SMILES do not preserve the full document’s jobs, provenance and drawing annotations.

Scheme PNG and PDF require the optional publication backend. A base install retains single-structure ACS PNG; install the publication extra for full drawing exports and DPI control. RXN export requires exactly one reaction. Unsupported exports return an explicit reason; see publication figures and the format table.

On a minimal Linux installation, a figure export can fail because RDKit’s rendering libraries are missing. Install the system libraries listed in installation and retry.

If a REST document says dirty: false but has file: null, it still exists only in memory. Export it before stopping the server. A saved file and an open document are different things; see response fields. For scripts, atomic saving avoids partial files but is not a general concurrent edit check; see file-writing guarantees.

Inputs and queue runs

Writers refuse unsupported combinations rather than dropping settings. Read all refusal reasons, compare the request with the writer reference, and ensure the selected species has a 3D conformer. Batch preparation may write some inputs and refuse others; CLI exit status 3 and API refused entries identify partial failure.

Writing an input does not require the target calculation program, but running it does. Queue submission additionally needs a configured, running vibe-queue with the selected program registered. GET /api/queue reports availability; see integration checks and the queue lifecycle tutorial.

A submission can succeed for only some species. Inspect the document’s runs before resubmitting so you do not launch duplicate calculations. Sending a prepared structure to vibe-view is a geometry hand-off, not retrieval of a completed calculation result.

API conflicts and reporting a problem

For a 409 or 412 revision conflict, read the latest document and reconcile the edit before retrying. Save can also return 409 for a missing backing file or protected QVF, so read the response detail rather than treating every 409 as a stale revision. The REST reference describes each case.

When reporting a problem, include the version, installation route, operating system, exact command or UI steps, and the error or refusal text. Supply a small non-confidential structure that reproduces it where possible. Remove private paths, hostnames, credentials and unpublished chemistry from logs before sharing them.