# What to Do When the AutoRemesher GUI Won't Start: Troubleshooting Guide

> Can't start the AutoRemesher GUI? Troubleshoot missing Qt plugins, OpenGL issues, or headless mode problems. Get your AutoRemesher working again with this guide.

- Repository: [Jeremy HU/autoremesher](https://github.com/huxingyi/autoremesher)
- Tags: troubleshooting-guide
- Published: 2026-07-10

---

**When the AutoRemesher GUI won't start, the issue typically stems from missing Qt platform plugins, insufficient OpenGL 3.3 support, or unintentional activation of headless mode via command-line arguments.**

The open-source AutoRemesher application by huxingyi/autoremesher provides automatic quad remeshing for 3D models through both a graphical interface and command-line interface. When the GUI fails to launch, the problem usually occurs during the initialization sequence defined in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp), before the MainWindow is ever instantiated. Understanding the specific failure points in the startup code helps you resolve environment configuration issues quickly.

## Common Causes of Startup Failure

### Missing Qt Platform Plugins (Linux)

The application aborts immediately if Qt cannot load its platform plugin, typically `xcb` on Linux systems. In [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) at line 22, the code creates the `QApplication` instance: `QApplication app(argc, argv);`. If the platform plugin is missing, the process terminates here with an error like *"Could not find or load the Qt platform plugin 'xcb'"* before reaching the MainWindow constructor.

### OpenGL 3.3 Compatibility Issues

AutoRemesher requires an OpenGL 3.3 core profile context. The code in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) (lines 33-36) explicitly sets this requirement:

```cpp
QSurfaceFormat format;
format.setVersion(3, 3);
format.setProfile(QSurfaceFormat::OpenGLContextProfile::CoreProfile);
QSurfaceFormat::setDefaultFormat(format);

```

If your graphics driver cannot provide OpenGL 3.3, the window creation fails and the program exits silently.

### Accidental Headless Mode Activation

Supplying the `--input` argument triggers headless mode, which processes models without displaying the GUI. At line 29 of [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp), the code checks `bool headlessMode = parser.isSet("input");` and skips the MainWindow instantiation if this flag is present.

### Missing Runtime Libraries

The executable requires Qt5 (Core, Gui, Widgets, OpenGL), system OpenGL libraries, and on Windows, the Visual C++ redistributable. The `.pro` file lists these dependencies, but missing DLLs or shared objects will prevent startup entirely.

## How to Diagnose the Problem

1. **Launch from a terminal** to capture Qt's error messages printed to `stderr`. Plugin loading failures and OpenGL initialization errors appear in the console output.

2. **Check OpenGL support** by running `glxinfo | grep "OpenGL version"` on Linux or using the OpenGL Extensions Viewer on Windows/macOS. The reported version must be at least 3.3.

3. **Test headless mode** to verify the binary integrity: run with `--input model.obj --output test.obj`. If this works but the GUI doesn't, you have a graphics or Qt platform issue.

4. **Inspect library dependencies** using `ldd ./autoremesher | grep Qt` on Linux or Dependency Walker on Windows to confirm all Qt libraries are found.

## Step-by-Step Solutions

### Fix Qt Platform Plugin Errors (Linux)

Install the required XCB plugins and dependencies:

```bash
sudo apt-get install libxcb-xinerama0 libxcb-icccm4 libxcb-image0 \
                     libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 \
                     libxcb-xkb1 libqt5gui5 libqt5core5a

```

If plugins are installed but not found, explicitly set the path:

```bash
export QT_QPA_PLATFORM_PLUGIN_PATH=/usr/lib/qt5/plugins/platforms
./autoremesher

```

### Ensure OpenGL 3.3 Support

**Linux**: Install Mesa drivers for Intel/AMD or proprietary drivers for NVIDIA:

```bash

# Intel/AMD

sudo apt-get install mesa-utils libgl1-mesa-dri

# NVIDIA

sudo apt-get install nvidia-driver

```

**Windows**: Download the latest drivers from your GPU vendor (NVIDIA, AMD, or Intel).

**macOS**: Use macOS 10.14+ on Metal-compatible hardware; Qt automatically handles the OpenGL compatibility layer.

### Verify Command-Line Arguments

Remove the `--input` flag if you intend to use the GUI. To run in headless mode intentionally (useful for servers or batch processing):

```bash
./autoremesher --input path/to/model.obj \
               --output result.obj \
               --target-quads 40000 \
               --report log.txt

```

### Check Runtime Dependencies

On Linux, verify library resolution:

```bash
ldd ./autoremesher | grep -i "not found"

```

On Windows, place the following DLLs in the same directory as `autoremesher.exe`:
- `Qt5Core.dll`
- `Qt5Gui.dll`
- `Qt5Widgets.dll`
- `Qt5OpenGL.dll`

### Rebuild with Fallback OpenGL (Advanced)

If you cannot obtain OpenGL 3.3, modify [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) lines 33-36 to request OpenGL 2.1:

```cpp
QSurfaceFormat format = QSurfaceFormat::defaultFormat();
format.setProfile(QSurfaceFormat::OpenGLContextProfile::CompatibilityProfile);
format.setVersion(2, 1);
QSurfaceFormat::setDefaultFormat(format);

```

Recompile with `qmake && make`. Note that this may reduce visual quality or 3D viewport performance.

## Summary

- **Missing Qt plugins** are the most common Linux startup failure; install `libxcb-*` packages and verify `QT_QPA_PLATFORM_PLUGIN_PATH`.
- **OpenGL 3.3 is mandatory** for the GUI; update drivers or modify [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) to use OpenGL 2.1 if hardware is incompatible.
- **Headless mode** bypasses the GUI entirely when using the `--input` flag; remove this argument to launch the interface.
- **Check console output** when diagnosing, as Qt prints critical plugin and context errors to `stderr` before the GUI appears.
- **Reference [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp)** to understand that initialization fails at `QApplication` creation (line 22) or OpenGL setup (lines 33-36) before MainWindow loads.

## Frequently Asked Questions

### Why does AutoRemesher crash immediately without showing a window?

The crash typically occurs during `QApplication` initialization in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) (line 22) when Qt cannot load its platform plugin, or during OpenGL context creation (lines 33-36) if your driver lacks OpenGL 3.3 support. Run the application from a terminal to view the specific error message printed to `stderr`.

### Can I use AutoRemesher without a display or GUI?

Yes. Pass the `--input` and `--output` arguments to activate headless mode, as implemented in [`src/main.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/main.cpp) at line 29. This is ideal for remote servers or automated pipelines: `./autoremesher --input model.obj --output result.obj --target-quads 50000`.

### How do I check if my system supports OpenGL 3.3?

On Linux, run `glxinfo | grep "OpenGL version"`. The output must show version 3.3 or higher. On Windows, use the OpenGL Extensions Viewer from the Realtech VR website. macOS users need Metal-compatible hardware running macOS 10.14 or later.

### Where are error logs stored if the GUI never appears?

While the `LogBrowser` in [`src/mainwindow.cpp`](https://github.com/huxingyi/autoremesher/blob/main/src/mainwindow.cpp) (lines 71-76) captures logs for the GUI, startup failures occur before this initialization. However, you can capture early Qt messages by running in headless mode with the `--report` flag: `./autoremesher --input model.obj --report startup.log`. Check this file for initialization errors.