Troubleshooting

• The viewer crashed or vanished: the next time you open Orbitron it shows a crash-report banner in the Console panel (click Console at the bottom-left of the window) summarizing what happened. The banner appears only once, so copy it if you want to keep it. The full report is also saved as a file you can attach to a bug report — Help → Open Crash Reports Folder reveals it, or find it directly at ~/Library/Application Support/dev.Orbitron.Orbitron/crashes/ on macOS, ~/.local/share/orbitron/crashes/ on Linux, %LOCALAPPDATA%\Orbitron\Orbitron\data\crashes\ on Windows. To capture more detail on a problem you can reproduce, launch Orbitron from a terminal with RUST_LOG=info and watch the output while you trigger it.
• Something feels slow, or memory keeps climbing: open the Console panel to watch what Orbitron is doing — file opens and each analysis task load are logged there, and a warning appears if memory use climbs abnormally (a sign a very large file is straining the machine). Large outputs load in the background; the status bar and progress overlay show progress and offer a cancel button.
• Blank window / GPU warnings: ensure GPU drivers are available. If you built Orbitron from source, activate the workspace conda environment before launching. Set WGPU_BACKEND=gl as a fallback or run the CLI/TUI headless.
• Viewer stuck “Loading…”: watch the status bar for byte progress. Streaming parsers update while they consume the file; whole-text formats may jump from the initial state to the exact file length after mapping or copying. A slow percentage with changing byte counts is still making progress. Esc cancels the current file dialog; the progress overlay includes a cancel button tied to CancelHandle.
• Loader says “Unsupported format”: run orbitron inspect <file> to see what the detector found and which loader ran. If the content is new, follow the new-format checklist in the Developer Guide.
• Gaussian/NWChem task missing from Tasks panel: run the CLI inspect command to view stage/task boundaries. If the summary exists but the panel is empty, file an issue with the CLI output attached.
• NWChem file shows Run incomplete or a failed task: This is expected when NWChem stops before its final completion marker or reports an error. Orbitron still retains every task it could summarize. It automatically opens the best completed task, so a finished optimization remains available when a following frequency calculation was interrupted. Incomplete and failed task cards remain visible in Analysis → Tasks, but are marked Unavailable rather than attempting a partial task load that could end in a generic error. Use orbitron inspect <file> to examine the file-level and per-task outcomes from the command line.
• QE PDOS/XSF not detected: confirm the PDOS files follow QE’s projwfc.x naming (*.pdos_*) and the volumetric grids are CUBE-style (Orbitron treats .xsf like CUBE). Running orbitron inspect --json <file> should show extras.qe.pdos_summary or a volumetric payload if parsing succeeded.
• The camera moved, or cats appeared, while I was away: those are the idle companions. After the viewer has been idle for a few minutes (5 by default), pixel cats wander into the viewport and may bat or head-bump the molecule, which moves the camera but never edits the structure. Any mouse or keyboard input puts the camera back where it was. Turn them off with View → Idle Companions → Show cats when idle, or change the delay there; see Idle companions.
• Edit mode commands fail silently: ensure atoms are selected before invoking “Change Element” or “Add Bond”; many menu items are intentionally disabled when the prerequisites are missing.
• SMILES construction is refused: Orbitron does not silently discard stereochemistry or query syntax. Remove @, @@, /, \\, wildcards, atom maps, reactions, SMARTS, or CXSMILES features, or import a MOL/SDF file from a tool that supports them. Metal-containing SMILES are also refused.
• Conformer generation is unavailable: the search accepts one connected, non-periodic, non-metal molecule of at most 200 atoms. Every atom needs a UFF type, at least one atom must be movable, and a candidate must preserve the starting stereochemistry.
• Residue mutation is unavailable: select atoms from exactly one PDB/mmCIF residue with N, CA, and C backbone annotation. Choose HID, HIE, or HIP instead of ambiguous HIS. Non-standard residues, nucleic acids, and structures without residue annotation are outside this command.
• Terminal-cap preview is unavailable: select atoms from exactly one observed protein-fragment end with one N, CA, and C backbone. ACE applies only to an N end and NME only to a C end. Orbitron refuses an internal residue, an already capped end, or unresolved alternate backbone atoms. The cap preview contains heavy atoms; run Adjust Hydrogens after applying if explicit cap hydrogens are required.
• Residue protonation preview is unavailable: select atoms from exactly one ASP/ASH, GLU/GLH, CYS/CYM, or LYS/LYN residue. Acidic states require an explicit oxygen tautomer. CYX, Tyr, Arg, non-standard residues, conflicting alternate sites, and structures without residue annotation are outside this command. Orbitron uses atom-record formal charges and does not infer a state from pH or from a PDB residue name.
• An edited protonation bond order disappeared after PDB export: PDB export preserves supported residue names, explicit atoms, and formal charges, but it does not write connectivity or bond order. Save an orbpack for an Orbitron-native round trip or use Molfile when a connection table is required.
• Disulfide creation or cleavage is unavailable: select atoms spanning exactly two annotated CYS/CYX residues with one SG atom each. Creation requires two CYS residues, no existing bridge or declaration, and a minimum-image SG-SG distance from 1.7 through 2.5 Å. Cleavage requires an SG-SG bond or PDB/mmCIF declaration. Move a distant pair explicitly before creation; Orbitron does not move heavy atoms in this command.
• A raw mmCIF _struct_conn row still appears after disulfide cleavage: Orbitron retains imported raw rows as source provenance. The live SG-SG bond and active SSBOND metadata are updated. PDB export reflects the active SSBOND state; Molfile or orbpack is required when the complete edited connection table must survive.
• NBO/Orbital meshes missing: confirm the CUBE/NBO files include volumetric data. The Orbital panel logs suggested isovalues and mesh statistics to the status toasts and the terminal (tracing output).
• A memory check (“… is projected to need about N GB, and M GB is free”): before opening a large file, loading an analysis task, computing surfaces, or building a supercell, Orbitron projects the operation’s peak memory and compares it to what’s free on your machine. The desktop asks before continuing, the CLI and TUI prompt only in an interactive terminal, and the Python API emits a warnings.warn. A scripted CLI run continues through a warning-band estimate but refuses a critical estimate; --allow-large permits that critical advisory case after you check the risk. It cannot override a configured hard cap or a projection beyond physical memory and swap. Set a hard limit with --max-memory <bytes> (CLI) or Orbitron(max_memory=…) (Python). The default is no hard cap. See Bundles §6.11 for current format multipliers, NWChem examples, renderer measurements, and scheduler guidance.
• A file shows results that look out of date: parsed files are cached on disk as canonical documents, keyed by the file’s contents. Each cached parse records a stamp of the build that produced it (the Orbitron version, a parser revision, and a hash of the parser source) and is re-parsed automatically whenever a different build reads it, so an upgrade, a downgrade, or a locally rebuilt parser picks up its own results for files you had already opened. (Releases before this stamping existed are re-parsed too.) This is the on-disk parse cache, not an .orbpack bundle — a bundle is a file you keep, and an old one is refused rather than re-parsed; see the next entry. If a run still seems to be missing data you expect and the file itself has not changed, clear the cache with orbitron canonical cache purge and reopen — orbitron canonical cache path shows where it lives, and list shows what is in it.
• An .orbpack bundle refuses to open, naming a schema version: the message reads unsupported orbpack schema <version>; this Orbitron reads major version 3. Bundles written before schema 3 held a single canonical document and cannot express a calculation made of several sources, so there is nothing to upgrade in place. Re-export the run from the original output with orbitron canonical export, on the machine the sources live on.
• Large file safeguards (byte cap): the file-size cap defaults to unlimited now that the memory projection is the guard. To hard-cap by file size instead, use the CLI --max-file-size flag, persist a default via orbitron config set-thresholds, set it in the desktop’s Preferences, or pass Orbitron(max_file_size=…) in the Python API. The desktop refuses a file over it before reading anything, naming the file’s size and the limit.
• “… has N atoms, over the configured limit”: the atom and bond caps (max_atoms, default 5,000,000, and max_bonds, default 10,000,000) apply to the CLI, the Python API and the desktop alike. The desktop checks them once the file is parsed and keeps the document that was open before. Raise or clear them with orbitron config set-thresholds --max-atoms and --max-bonds (0 is no limit); Preferences does not show them. The desktop counts bonds only when the file states them, so a structure whose bonds are perceived from distances is held to the atom limit alone.

For architecture and extension guidance continue to the Developer Guide.

For advanced workflows (authoring new parsers, editing commands, or renderer integrations) continue to the Developer Guide.