Skip to content

Troubleshooting Common Issues

Jump to bottom
Hiromichi Yokoyama edited this page Aug 4, 2026 · 2 revisions

Troubleshooting Common Issues

This page covers issues that are traceable to MoleditPy's actual source code or to documented behavior elsewhere in this wiki. It intentionally does not speculate about symptoms nobody has reported.

1. First launch is slow

This is expected and self-resolving. Per the app's own README/Home page, the very first run after installing (or after upgrading) commonly takes noticeably longer than every run after it, for two independent reasons:

  1. Matplotlib builds its font cache. The first time Matplotlib (used by several plugins, e.g. NMR/MS/spectrum analyzers) runs on a machine, it scans installed fonts and writes a cache; you may see a console message about this. It only happens once.
  2. Python compiles .pyc bytecode caches for large libraries — RDKit, PyVista/VTK, and (on Windows/macOS) OpenBabel — the first time each is imported after an install or Python-version change. moleditpy-linux's dependency stack is smaller (see §4 below) but is not exempt from this in general.

If launches stay slow on every run (not just the first), that's not this issue — see §3 for OpenGL/VTK-related slowness/failures instead.

2. Qt platform plugin errors ("could not load the Qt platform plugin", headless/SSH/CI)

If you run moleditpy over SSH, inside a container, or on a CI runner with no display attached, Qt's default platform backend (xcb on Linux) cannot initialize, and PyQt6 fails to start with an error mentioning the Qt platform plugin. Set:

export QT_QPA_PLATFORM=offscreen
moleditpy

QT_QPA_PLATFORM is not read by MoleditPy's own code at all — it's consumed by Qt itself before any moleditpy Python code runs, which is why it must be set as an environment variable rather than a CLI flag. See Command-Line Options for how this combines with MOLEDITPY_HEADLESS=1 (which additionally suppresses MoleditPy's own blocking error/warning dialogs, so an automated run can't hang waiting for a click). This is exactly the combination MoleditPy's own test suite uses to run headlessly (MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen python tests/run_all_tests.py ..., per the main app's CLAUDE.md).

Note that QT_QPA_PLATFORM=offscreen gives you a fully headless process with no visible window at all — this is for automation/testing, not a fix for "the window doesn't show up" on a normal desktop session (see §3 for that).

3. 3D view fails to appear, is blank, or crashes on startup (OpenGL/VTK)

MoleditPy's 3D panel is a CustomQtInteractor (a pyvistaqt/VTK widget) created directly in MainWindow's init path (ui/main_window_init.py: _init_right_panel) with no try/except around its construction — if the underlying OpenGL context or VTK rendering backend can't initialize (typically: no GPU driver, a headless/remote-desktop session without proper GL support, or a broken Mesa/graphics-driver install on Linux), this surfaces as an immediate crash with a VTK/OpenGL traceback in the terminal, rather than a graceful in-app error message.

What to check:

  • On Linux, make sure Mesa/OpenGL userspace drivers are installed (libgl1-mesa-dev/equivalent for your distro) and that you're not trying to run inside an environment with no GPU/software-rendering path at all. Remote sessions (VNC/RDP/X-forwarding) sometimes lack proper GLX support — a local session is the most reliable environment.
  • This is separate from QT_QPA_PLATFORM=offscreen (§2) — offscreen mode has no on-screen window at all, so it sidesteps this class of problem entirely (useful for confirming whether a crash is graphics-related: if it launches fine under offscreen, the problem is specifically your display/OpenGL setup, not MoleditPy).
  • If the crash happens only with certain advanced 3D display styles/effects (PBR, SSAO, EDL, Depth Peeling — these are added by the official Advanced Rendering/Cube File Viewer Advanced plugins), try switching back to the built-in styles (Ball & Stick, CPK, Wireframe, Stick) first to isolate whether the problem is in the base VTK pipeline or in one of those effects.

4. Linux: OpenBabel is disabled, "3D Conversion" fallback doesn't happen

On Linux, install moleditpy-linux (not plain moleditpy — pip install moleditpy-installer picks the right one automatically per platform). In this distribution, OpenBabel support is hardcoded off: moleditpy_linux/__init__.py sets OBABEL_AVAILABLE = False unconditionally (not detected — always disabled), specifically to avoid library conflicts between OpenBabel's bundled native libraries and the rest of the Linux dependency stack. Consequences:

  • The RDKit→OpenBabel fallback during 2D to 3D conversion does not exist on Linux — if RDKit's embedding fails for a given molecule, there is no automatic second attempt.
  • Any 3D-optimization method selection that specifically requires OpenBabel is unavailable.
  • This is a deliberate, permanent trade-off for this platform, not a bug to file — see the Installation for Linux page for the full install story.

5. Plugin fails to load, or a plugin broke the app on startup

Open Plugin ▸ Plugin Manager... and look at the Status column:

Status Meaning
Loaded (green) Working normally.
No Entry Point (gray) The plugin file has none of initialize(), run(), or autorun() — it did nothing, by design or by mistake in the plugin itself.
Error (Init): ... / Error (Autorun): ... (red) The plugin's initialize()/autorun() raised an exception during startup; the message is shown right in that cell, and the full traceback is written to the log (console, or the log file if enabled — see §7).
(missing entirely) A plugin whose file fails to even import (a syntax error, a missing required third-party package at module level, etc.) never makes it into this table at all — it's caught, logged as a warning, and silently skipped. If you expect a plugin to appear and it doesn't, check the console output or log file for a "Failed to load plugin ..." warning.

Reload Plugins in the same dialog re-scans and re-executes everything without restarting — useful after fixing a plugin file in place.

If a plugin's failure is severe enough to crash MoleditPy itself before you can even reach the Plugin Manager, launch with:

moleditpy --safe

which skips loading every plugin (no plugin file is even read), so you can get back into a working app, remove/investigate the offending plugin from ~/.moleditpy/plugins/ (or via Open Plugin Folder if you can reach it in a working session), and relaunch normally. See Using Plugins and Command-Line Options for more on safe mode.

6. Plugin Installer: version/OS/dependency mismatches

If a plugin is greyed out or won't install through the Plugin Installer plugin, it's most likely one of:

  • supported_moleditpy_version — the plugin declares a version range for the main app that your installed MoleditPy doesn't satisfy.
  • supported_python_version — similarly for your Python interpreter.
  • supported_os — some plugins are restricted to specific operating systems where their backend can actually run (for example, the PySCF Calculator plugin lists only macOS/Linux/WSL, because PySCF itself is documented to be unreliable to install on Windows).
  • A missing Python dependency — the Installer checks each plugin's declared dependencies via importlib.metadata and offers a "Copy install command" you can run yourself (e.g. pip install pyscf geometric) before the plugin will actually function, even if the plugin file installs successfully.
  • A SHA-256 mismatch between the downloaded file and the registry's recorded hash hard-blocks installation outright (this is a deliberate integrity check, not a bug) — if you hit this, it usually means either a corrupted download or a stale local copy of the registry; try again.

7. Where the log file is (and how to turn it on)

By default, MoleditPy logs to the console only (stdout) at INFO level. To persist logs across sessions:

Settings ▸ Settings... ▸ Other tab:

  • "Save log to file (~/.moleditpy/moleditpy.log)" — check this to also write logs to ~/.moleditpy/moleditpy.log. It's a rotating log: capped at 1 MiB per file, keeping 3 backups (moleditpy.log, moleditpy.log.1, .2, .3), so it won't grow without bound.
  • "Enable DEBUG level logging" — raises the log level from INFO to DEBUG for much more detail (useful when reporting a bug).

Both settings are read once, at startup, from ~/.moleditpy/settings.json — toggling them takes effect on the next launch, not immediately (main.py: _read_startup_log_settings() runs before the GUI or the settings dialog even exists).

Every ERROR/CRITICAL-level log record (including uncaught exceptions, which are funneled through sys.excepthook) also pops a non-blocking "MoleditPy — Error" dialog with the message and a Show Details... traceback, unless: you're running under MOLEDITPY_HEADLESS=1 (dialogs are disabled entirely so an automated run can't hang), the same error already showed a dialog within the last 10 seconds (deduplicated so a fast-repeating error doesn't spam you), or another modal dialog is already active at that instant (the generic dialog stays quiet so it doesn't stack on top of a more specific error dialog a feature already showed).

8. See also

Clone this wiki locally