Troubleshooting

• 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 background progress. Esc cancels the current file dialog; the progress overlay includes a cancel button tied to CancelHandle.
• Remote connection fails: confirm ssh <host> works from a terminal (the same ~/.ssh/config, agent, and 2FA apply). A key passphrase or 2FA prompt appears in the launching terminal on first access. “No such file” means the path is wrong relative to the configured remote root.
• 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.
• 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).
• Large file safeguards: override the default 500 MB loader cap with ORBITRON_MAX_FILE_SIZE or the services config (--max-file-size via 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.