Skip to content

Troubleshooting Common Issues

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

Troubleshooting common issues

This page covers problems you may hit while using MoleditPy day to day — slow startup, the 3D view or a plugin misbehaving, and file import/export failures. If you are debugging a headless install, CI run, or want to enable logging, see the advanced/diagnostic section at the end.

First launch is slow

This is expected and self-resolving. 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) Open Babel — the first time each is imported after an install or Python-version change. moleditpy-linux's dependency stack is smaller (see Linux: 3D conversion doesn't fall back to Open Babel) but is not exempt from this in general.

If launches stay slow on every run, not just the first, that is not this issue — see the next section for 3D/OpenGL-related slowness or failures instead.

The 3D view is blank, or the app crashes when it opens

MoleditPy's 3D panel is built directly at startup, with no fallback if the underlying OpenGL context or VTK rendering backend can't initialize. Typical causes: no GPU driver, a headless/remote-desktop session without proper GL support, or a broken Mesa/graphics-driver install on Linux. This shows up as an immediate crash with a VTK/OpenGL traceback in the terminal rather than an in-app error message.

What to check:

  • On Linux, make sure Mesa/OpenGL userspace drivers are installed (libgl1-mesa-dev or your distro's equivalent), and that you are not running in 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.
  • If the crash happens only with certain advanced 3D display styles or effects (PBR, SSAO, EDL, Depth Peeling — added by the official Advanced Rendering/Cube File Viewer Advanced plugins), switch back to a built-in style (Ball & Stick, CPK, Wireframe, Stick) first, to isolate whether the problem is in the base VTK pipeline or in one of those effects.
  • To confirm whether a crash is graphics-related at all, launch with QT_QPA_PLATFORM=offscreen set (see Qt platform plugin errors below). If it launches fine that way, the problem is specific to your display/OpenGL setup, not MoleditPy — though note that mode has no visible window, so it only isolates the cause, it isn't a usable workaround for normal desktop use.

A plugin fails to load, or breaks the app on startup

Open Plugin > Plugin Manager... and check the Status column:

Status Meaning
Loaded (green) Working normally.
No Entry Point (gray) The plugin file defines 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 in that cell, and the full traceback is written to the log (console, or the log file if enabled — see Log files and debug logging).
(missing entirely) A plugin whose file fails to even import (a syntax error, a missing required third-party package, etc.) never appears in this table at all — it is 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 before you can even reach the Plugin Manager, launch with:

moleditpy --safe

This skips loading every plugin (no plugin file is even read), so you can get back into a working app, remove or 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.

The Plugin Installer greys out or won't install a plugin

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

Cause What it means
supported_moleditpy_version The plugin declares a version range for the main app that your installed MoleditPy doesn't satisfy.
supported_python_version Same idea, for your Python interpreter.
supported_os Some plugins are restricted to 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.
Missing Python dependency The Installer checks each plugin's declared dependencies 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.
SHA-256 mismatch A mismatch between the downloaded file and the registry's recorded hash hard-blocks installation outright — this is a deliberate integrity check, not a bug. It usually means either a corrupted download or a stale local copy of the registry; try again.

File import or export problems

Symptom Likely cause What to do
MOL Import Error dialog when opening a .mol/.sdf file The file is corrupted, hand-edited into an invalid state, or isn't actually a MOL/SDF file Re-export the file from its original source; check that the extension matches the actual content
Invalid SMILES / Invalid InChI on the status bar The typed string doesn't parse under RDKit's rules Double-check the string; this is reported on the status bar, not a popup, so it's easy to miss
"This file is not a valid PME Project format." when opening a .pmeprj The file isn't a MoleditPy project file, or its "format" marker was altered Confirm you're opening a genuine .pmeprj; a mismatched "version" field still loads with a warning rather than failing outright
.pmeraw file won't open, or you're wary of opening one This is the legacy Python-pickle format, which can execute arbitrary code on load Only open .pmeraw files you created yourself; prefer .pmeprj for anything you share with others
Import XYZ Charge dialog appears when importing a .xyz file RDKit couldn't determine bonds automatically from geometry alone at charge 0 Enter the correct total molecular charge, or click Skip chemistry to fall back to distance-based bond estimation

See File Formats and Import/Export for the full list of formats MoleditPy reads and writes, and what each plugin adds on top.

Linux: 3D conversion doesn't fall back to Open Babel

On Linux, install moleditpy-linux (not plain moleditpy — pip install moleditpy-installer picks the right one automatically per platform). In this distribution, Open Babel support is disabled unconditionally, to avoid library conflicts between Open Babel's bundled native libraries and the rest of the Linux dependency stack. Consequences:

  • The RDKit-to-Open-Babel 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 that specifically requires Open Babel is unavailable.
  • This is a deliberate, permanent trade-off for this platform, not a bug — see Installation for Linux for the full install story.

Advanced / diagnostic

The rest of this page is for headless environments, CI, and debugging with logs — most users will not need it.

Qt platform plugin errors (headless/SSH, or 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 is 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).

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.

Log files and debug logging

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

  • 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.

Every ERROR/CRITICAL-level log record (including uncaught exceptions) 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), 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.

See also

Clone this wiki locally