Troubleshooting
Resolve common structure, browser, command, and device issues.
The browser bindings report that WebGPU is unavailable
Use current Chrome or Edge. Safari and Firefox require WebGPU to be enabled. The bindings render in the page's browser; changing a Python kernel does not add browser WebGPU support.
Atoms appear without sticks
Infer bonds after reading an mmCIF when you need ball-and-stick, licorice, or lines:
import molframe
structure = molframe.read("structure.cif").infer_bonds()A command fails
Catch molgfx.CommandError and inspect its located errors. A multi-statement program is atomic, so correct the bad statement and run the program again rather than recovering a partly changed scene.
The scene is blank or too broad
Start from protein, ligand, or a named ligand selection. Use scene.focus("resname HEM") or a focus command to direct attention to a local region. When no atoms match, test the query alone with len(structure.select(...)) and see Writing queries and commands.
Native image rendering cannot open a device
Call molgfx.system_info() and inspect available_adapters. Update the platform graphics driver or render on a machine with a compatible adapter. Do not assume browser WebGPU availability implies that a headless native environment can open the same device.
Completion metrics are not interchangeable
Frame reports distinguish submission, callback-recorded host completion, and device timestamp execution when the backend supports GPU timestamps. Browser callback latency is not exact GPU execution time, and unsupported timestamp queries are unavailable rather than zero. A settled scene should not continue submitting frames merely to poll completion; completion callbacks wake only work that is pending.
Verification status
The canonical browser suite passed on macOS arm64 with Playwright 1.63.0 and
Chromium 153.0.8010.12, using the full chromium channel and
--enable-unsafe-webgpu. It covers physical resize, exact semantic atom picks,
camera input, independent viewers, disposal during real GPU readback and React
StrictMode. Idle and post-disposal GPU submissions were zero over 300 ms.
Synthetic 1,000-, 10,000- and 50,000-atom workloads measure load, command,
host-observed GPU completion and camera redraw costs; these are measurements,
not a claimed speedup or exact device execution times.
The older Chromium headless-shell on this macOS host failed physical resize and multiple-device lifetime checks; the suite therefore uses full Chromium. Linux CI additionally requests ANGLE/Vulkan SwiftShader and disables Vulkan surface presentation. This change has not been exercised here on Linux, Safari or Firefox. Cross-engine capability, device timestamps and high-DPI picks are not claimed by this run. Packed npm consumers passed production Vite 6.4.3 and Next 16.3.5 builds and loaded their emitted wasm assets in the real browser.