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. 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 incomplete or failed tasks: This is expected behavior when NWChem jobs terminate early or encounter errors. Check the colored status circles in the Analysis → Overview panel: green indicates complete tasks, yellow indicates incomplete but usable data, red indicates failed tasks, and gray indicates unknown status. Orbitron automatically selects the best complete task on file load. You can manually click any task (even incomplete ones) to load whatever data is available—optimizations may have partial geometries, frequency analyses may have some modes. If all tasks are incomplete/failed, you’ll see a toast notification and can still inspect task details in the Analysis tab. Use orbitron inspect <file> to examine task boundaries and 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.
• 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).
• “This will need more memory than you have” warning: 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. Bundles record the Orbitron version that produced them and are re-parsed automatically when a newer version reads them, so an upgrade picks up parser fixes on files you had already opened. (Releases before this stamping existed are re-parsed too.) 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.
• 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, or pass Orbitron(max_file_size=…) in the Python API.

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.