Troubleshooting

Welcome to the troubleshooting page. Since shapeXT heavily relies on modern graphics APIs (specifically Vulkan 1.3 and above) to achieve its high rendering performance, most common issues are related to graphics drivers or hardware compatibility.

Please find known issues and solutions for your operating system below. If your problem is not listed here, please press F8 inside the application to submit a bug report, or contact me via email at mail@shapeXT.com.

• Symptom: shapeXT becomes noticeably sluggish when entering full-screen mode or running at high display resolutions.
• Cause: Running at full-screen (especially on high-resolution displays like 1440p or 4K) significantly increases GPU memory (VRAM) consumption. Because shapeXT uses multiple render buffers alongside multi-sample anti-aliasing, the default setting (4xMSAA + FXAA) can exceed your graphics card's available VRAM. When VRAM fills up, the driver swaps memory to system RAM, causing a steep performance drop.
• Solution: Try the following steps to reduce VRAM usage:
  • Option 1: Reduce Anti-Aliasing (Recommended)
    1. Go to the menu bar and select Options → Anti-Aliasing.
    2. Change the setting to FXAA (or Off). FXAA is a post-processing filter that provides clean edge smoothing without requiring additional VRAM.
    3. If your GPU has moderate VRAM headroom, you can also test intermediate options like 2xMSAA + FXAA to balance visual quality and performance.

• Option 2: Reduce the Transparency Alpha Buffer Size (Not Recommended)
  1. By default, shapeXT reserves 1024 MiB (1 GB) of VRAM for Order-Independent Transparency (OIT) to correctly render complex overlapping molecular/crystal structures.
  2. Open the configuration file located at Config/Vulkan.toml in the shapeXT main folder with a text editor.
  3. Locate the AlphaBufferSize parameter and lower its value (e.g., to 512 MiB):
  4. Note: Lowering this buffer frees up significant VRAM, but if the buffer becomes too small, transparency effects may exhibit rendering artifacts.

• Symptom: shapeXT fails to start, throws a graphics-related error, or you suspect your drivers are outdated.
• Cause: Your system might be missing proper or up-to-date Vulkan drivers.
• Solution: You can verify your Vulkan support using the free diagnostic tool GPU-Z.
  1. Download and run TechPowerUp GPU-Z.
  2. Look at the bottom of the main window.
  3. Check if the box next to Vulkan (in the “Computing” or “Technologies” section) is ticked with a green checkmark (red box).
  4. If it is not checked, please download and install the latest graphics drivers directly from your GPU manufacturer's website (NVIDIA, AMD, or Intel).

• Symptom: You launch shapeXT.exe, the main window briefly flashes with a white background, and then immediately closes/crashes.
• Cause: This is a known bug in the current beta version (v2026.06.0) related to Vulkan initialization on systems using integrated Intel Arc graphics.
• Solution: A fix was provided in version v2026.06.1.

• Symptom: shapeXT cannot be opened, crashes immediately, or macOS displays an architecture/compatibility warning.
• Cause: shapeXT has been optimized for modern Mac hardware and only supports Apple Silicon chips (M-series).
• Solution: Older Intel-based Macs are not supported. To run shapeXT, you need a Mac with an Apple Silicon processor. You can verify your processor by clicking the Apple Logo in the top-left menu bar and selecting About This Mac.

• Symptom: Running the shapeXT.sh script results in a crash, often accompanied by terminal output mentioning “Vulkan”, “VK_ERROR”, or “instance creation failed”.
• Cause: Missing or misconfigured Vulkan drivers on your Linux distribution.
• Solution: You can easily test if Vulkan is set up correctly on your system by using the vkcube utility.
  1. Open your terminal.
  2. Run the command: vkcube (you may need to install the vulkan-tools package first via your package manager, e.g., sudo apt install vulkan-tools).
  3. If a window opens showing a spinning 3D cube, your Vulkan installation is working properly and shapeXT should run.
  4. If vkcube fails to run or throws an error, you need to install the correct Vulkan drivers for your graphics card (e.g., mesa-vulkan-drivers, vulkan-radeon, or the proprietary NVIDIA drivers depending on your distribution).