Troubleshooting

Find the heading that matches what you see. If nothing here helps, report the problem at https://github.com/xpayn3/MeshOptimiser/issues. Say which version you have (click the app’s mark in the top bar) and paste the log: Copy log on the progress card, or the copy button in the console.

“python is not on PATH” on Windows

Windows cannot find Python. Run the Python installer again and tick “Add Python to PATH”. Or close and reopen the terminal or the launcher, so the new PATH is picked up. See What you need.

“Operation not permitted” on macOS

Right-click start.command and choose “Open”. macOS blocks a double-click on a freshly unzipped script the first time.

“ModuleNotFoundError: No module named ‘OCP’”

The Python environment is incomplete. The same goes for a missing numpy or trimesh. Quit the app, delete the folder .venv inside the app folder, and start the launcher again. It rebuilds the environment from scratch.

The first run stops while installing

• Check your internet connection. The first run has to download the add-ons.
• Check your Python version. The converter needs 3.10, 3.11 or 3.12. With 3.13 the add-ons cannot be installed. Install a supported version, delete the folder .venv if one was created, and start again.
• Check that the drive has about 2 GB free.

“This page needs a local server”

You opened index.html directly. Browsers do not let the app run that way. Start it with start.bat or start.command, and use the address the launcher prints, normally http://localhost:4242.

The app window is empty, or the browser cannot reach the page

The local server is not running. This happens when you open the installed app or a bookmark without starting the launcher first, or after you closed the launcher window. Start the launcher again.

The address is not localhost:4242

Something else on your computer was already using port 4242, so the server chose another one. That is fine. The launcher window prints the address it is using.

The app opened in a normal browser tab

The launcher found no Chrome, Edge or Brave, so it used your default browser. The app works the same in a tab.

The 3D view is empty or looks wrong

• Press F to frame the model, and AltH to show hidden parts.
• The viewer uses WebGPU when the browser has it and falls back to WebGL2 when it does not. To switch by hand, open Settings, Performance and set Renderer to WebGL2. The page reloads.
• If a message says the GPU was lost, reload the page.
• Update your browser and your graphics driver.

A STEP conversion takes very long

Large assemblies take time, and the reading of names, colours and the tree is the slowest part. The progress card keeps showing the converter’s latest message while it works. To make it faster, change the import settings:

• Leave SHUO overrides, Layer attributes and Validation properties (mass, area) off.
• Choose a coarser Tessellation quality.
• Set Drop parts smaller than (% of model) above 0 to skip tiny fasteners.
• For a huge file where you only need the shape, choose geometry only under Colours & materials.

Cancel on the progress card stops a conversion that is running.

“Conversion failed”

Press Copy log on the progress card and read the last lines. To see everything the converter prints, drag the STEP file onto test-converter.bat or test-converter.command. Include the log when you report the problem.

The model has no colours or no parts tree

A STEP file may have been converted with geometry only. Open it again and choose the option that reads colours, names and hierarchy under Colours & materials. A GLB, FBX, OBJ or STL file can only show what the file itself contains.

The view stutters on a heavy model

• Open Settings, Performance. Keep Skip tiny parts and Lower the resolution if it stutters on, and try Quality on Low.
• Make the model lighter. See A sensible order to work in.

Small parts disappear while I turn the view

That is Skip tiny parts at work. They come back the moment the view stops. Switch it off under Settings, Performance if you prefer.

A recent file asks me to pick it again

The browser needs a fresh permission before the app may read that file. Open it once more with Open file…, or drop it on the window.

The exported model is the wrong size or lies on its side

Export again with a different Unit scale or the other Up axis. See Export.

An export fails on a very large model

Text formats such as OBJ can run out of memory. Use GLB or STL, which are binary.

I closed the window and the app is still running

Closing the window does not stop the server. Close the launcher window too, or next time use Menu, then Quit app.