Introduction
Dwarf Therapist failing to open or crashing immediately on launch is one of the most frustrating problems a Dwarf Fortress player can encounter. You have a fortress to manage, dwarves to assign, and a tool that simply refuses to cooperate. The good news is that this category of problem almost always has a clear, fixable cause.
Launch failures in Dwarf Therapist are rarely random. They follow predictable patterns tied to version mismatches, missing dependencies, corrupted configuration files, permission restrictions, or conflicts with the operating system environment. Identifying which pattern applies to your situation is the first step toward resolving it.
This guide covers every major cause of Dwarf Therapist failing to open or crashing on launch, with step-by-step resolution instructions for Windows, Linux, and macOS. Each section is organized to get you from problem to solution as directly as possible.
Quick Answer about Dwarf Therapist
- Dwarf Therapist not opening is most commonly caused by a version mismatch with the installed Dwarf Fortress build, missing runtime dependencies, or insufficient system permissions
- Crashing immediately on launch most often points to a corrupted config file, an incompatible memory layout, or a missing Qt runtime library
- Windows users should check Visual C++ Redistributable installation and antivirus interference as the first two steps
- Linux users should verify Qt library availability and confirm ptrace permissions are correctly configured
- macOS users should check Gatekeeper security restrictions and confirm Xcode Command Line Tools are installed if running a source build
- Deleting or renaming the config file and relaunching will resolve crashes caused by corrupted configuration without affecting Dwarf Fortress saves
- Always launch Dwarf Fortress first and load a game before opening Dwarf Therapist to avoid process detection failures that can trigger crashes
- Running Dwarf Therapist as administrator or with elevated permissions resolves a significant portion of launch failures on Windows
- Community resources including the Dwarf Therapist GitHub Issues page and the Bay 12 Forums are reliable sources for version-specific crash reports and fixes
- If no fix resolves the issue, building Dwarf Therapist from source for your specific platform is a reliable fallback that bypasses most binary-related launch failures
What Causes Dwarf Therapist to Crash or Fail to Open
The Most Common Root Causes Explained
Dwarf Therapist depends on several external components to launch successfully. When any one of these components is absent, outdated, or conflicting, the application either fails silently, displays an error, or crashes before the main window appears.
The most frequent cause across all platforms is a version mismatch. Dwarf Therapist is tightly coupled to specific Dwarf Fortress versions through its memory layout system.
When the installed Dwarf Therapist release does not include a layout file matching the running game version, the application may crash during the memory detection phase rather than displaying a clean error message.
Missing or incompatible runtime libraries are the second most common cause. On Windows this typically means an absent Visual C++ Redistributable package.
On Linux it means Qt libraries that are either missing from the system or present in a version that does not match what the Dwarf Therapist binary was compiled against. On macOS it often involves a broken Qt framework path within the application bundle.
Corrupted configuration files, restrictive file permissions, and security software interference round out the remaining common causes.
Each of these produces distinct symptoms that can help narrow down the specific issue before attempting fixes.
Reading the Error to Identify the Problem
Before applying any fix, take note of exactly what happens when Dwarf Therapist fails. The behavior at the moment of failure is the most reliable diagnostic signal available.
If nothing visible happens when you attempt to launch, the executable is either blocked by security software, lacks execute permissions, or is missing a dependency that prevents the initial loading phase from completing.
If a brief window flashes and disappears, the application is starting but crashing during initialization. This is almost always a config file corruption, a missing Qt plugin, or a memory layout error triggered during startup.
If an explicit error message appears, read it carefully before doing anything else. Messages referencing missing DLL files on Windows, shared object files on Linux, or framework paths on macOS directly identify the missing component. Messages referencing version numbers or memory layouts point to a compatibility issue rather than a missing file.
How to Fix Dwarf Therapist Not Opening on Windows
Checking Dependencies and Permissions
The first step on Windows is confirming that the required Visual C++ Redistributable packages are installed. Dwarf Therapist requires the Microsoft Visual C++ Redistributable for Visual Studio, typically the 2015 through 2022 version covering both x86 and x64 architectures. These are available directly from Microsoft’s website at no cost.
Download and install both the x86 and x64 versions even if your system is 64-bit, as some components of Qt-based applications reference 32-bit libraries. After installation, restart your system and attempt to launch Dwarf Therapist again before proceeding to other fixes.
If the application still fails to launch, right-click the Dwarf Therapist executable and select Run as Administrator.
A significant number of Windows launch failures are caused by the application lacking sufficient permissions to access the Dwarf Fortress process memory or to write to its own configuration directory.
Check whether antivirus or security software is blocking the executable. Some antivirus products flag Dwarf Therapist as suspicious because it reads another application’s memory, which is behavior associated with certain types of malware even when the intent is entirely benign. Add Dwarf Therapist to your antivirus exclusion list and attempt the launch again.
Common Windows-specific launch problems and their resolutions:
- Missing MSVCP140.dll or VCRUNTIME140.dll error: Install or repair the Visual C++ 2015 to 2022 Redistributable from Microsoft’s official download page
- Application starts then immediately closes with no message: Check the Windows Event Viewer under Windows Logs then Application for a crash entry with more detail about the failure
- Antivirus quarantines the executable on launch: Add the full Dwarf Therapist folder to your antivirus exclusion list, then re-extract the application from the original download archive
- Access denied error when attempting to launch: Right-click the executable and select Run as Administrator, or adjust the folder permissions to give your user account full control
- Qt5Core.dll or similar Qt DLL missing error: The application was extracted incompletely; re-extract the full archive to a fresh folder and ensure all files from the archive are present
Resolving Config and Layout Issues on Windows
If dependency and permission checks pass but the application still crashes, the config file is the next target. Navigate to the config file location, which on Windows is typically the same folder as the executable or in %APPDATA%\DwarfTherapist. Rename the existing config file by adding .old to its filename rather than deleting it, which preserves it as a fallback.
Launch Dwarf Therapist again. The application will generate a fresh config file with factory defaults. If it now launches successfully, the original config file was corrupted. You can either continue with the fresh defaults or carefully compare the old file with the new one to identify and remove the corrupted entry.
If the application launches but immediately crashes when Dwarf Fortress is running, verify that the memory layout file for your specific Dwarf Fortress version is present in the layouts directory.
Navigate to the layouts folder within the Dwarf Therapist installation and look for a file whose name corresponds to your game version number. If it is absent, download it from the Dwarf Therapist GitHub repository and place it in that folder before relaunching.
How to Fix Dwarf Therapist Crashing on Linux and macOS
Linux-Specific Launch Failure Fixes
On Linux, the most reliable first step is launching Dwarf Therapist from a terminal rather than a file manager or desktop shortcut. This surfaces error output that would otherwise be hidden, giving you the exact library name or error code responsible for the failure.
Open a terminal, navigate to the Dwarf Therapist executable location, and run it directly:
cd /path/to/dwarf-therapist
./DwarfTherapistIf the output references a missing shared library such as libQt5Core.so or libQt5Widgets.so, install the missing Qt package for your distribution. On Debian and Ubuntu based systems:
sudo apt install libqt5core5a libqt5widgets5 libqt5x11extras5On Arch Linux:
sudo pacman -S qt5-base qt5-x11extrasIf the terminal output shows a permission error related to process attachment, the ptrace_scope setting is restricting Dwarf Therapist from reading Dwarf Fortress memory. Run the following to temporarily relax this restriction:
sudo sysctl kernel.yama.ptrace_scope=0
This setting has security implications on shared systems and resets after reboot. Apply it only on personal machines used for gaming, and be aware of what it means for your system’s security posture before making it permanent.
If the application crashes with a segmentation fault, the most likely causes are a Qt version mismatch between the compiled binary and the installed libraries, or a corrupted config file.
Delete the config file at ~/.config/DwarfTherapist/ and relaunch. If the crash persists after config deletion, rebuilding Dwarf Therapist from source for your specific Qt version is the most reliable resolution.
macOS-Specific Launch Failure Fixes
On macOS, Gatekeeper security restrictions are the first thing to address. When you attempt to launch a downloaded application that is not from the Mac App Store or a notarized developer, macOS will block it with a message stating the app cannot be opened because it is from an unidentified developer.
To bypass this for Dwarf Therapist, right-click the application and select Open rather than double-clicking it. A dialog will appear offering the option to open it anyway. Confirm this choice.
Once you have done this once, macOS will remember the exception and allow future launches normally.
If the application opens briefly and then crashes, open the Console application from Applications then Utilities and filter for Dwarf Therapist crash reports. The crash log will identify the specific framework or library that caused the failure, which is significantly more useful than the generic crash dialog.
For source-built installations on macOS, confirm that the Qt framework path within the application bundle is correctly set. A common issue after building with Homebrew is that the application bundle references the Homebrew Qt installation path, which can break if Homebrew updates Qt to a new major version.
Running macdeployqt on the compiled application bundle resolves this by embedding the Qt frameworks directly:
macdeployqt DwarfTherapist.app
| Symptom | Most Likely Cause | Platform | Primary Fix |
| Nothing happens on launch | Antivirus block or missing dependency | Windows | Check antivirus exclusions, install VC++ Redistributable |
| Flashes and disappears | Corrupted config file | All platforms | Rename or delete config file |
| Missing DLL error | Incomplete extraction or missing runtime | Windows | Re-extract archive, install VC++ Redistributable |
| Missing .so library error | Qt libraries not installed | Linux | Install Qt packages via package manager |
| Unidentified developer block | Gatekeeper restriction | macOS | Right-click and select Open |
| Crashes when game is running | Missing or wrong memory layout | All platforms | Verify layout file matches game version |
| Segmentation fault | Qt version mismatch or corrupt config | Linux/macOS | Rebuild from source or delete config |
| Access denied on launch | Insufficient permissions | Windows/Linux | Run as administrator or fix ptrace scope |
Frequently asked questions
Why does Dwarf Therapist crash only when Dwarf Fortress is running and not otherwise?
This points directly to a memory layout issue. Dwarf Therapist attempts to read the game memory when it detects a running Dwarf Fortress process, and if the layout file does not match the game version, the memory read fails and the application crashes.
Verify that the layout file in the layouts directory precisely matches your Dwarf Fortress version number.
How do I find the crash log for Dwarf Therapist on my platform?
On Windows, open Event Viewer and navigate to Windows Logs then Application, filtering for DwarfTherapist entries. On Linux, run the application from a terminal to capture stderr output directly. On macOS, use the Console application in Applications then Utilities and search for Dwarf Therapist crash reports. The crash log will contain the specific error responsible for the failure.
Will reinstalling Dwarf Therapist fix a launch crash?
Reinstalling resolves crashes caused by corrupted or incomplete file extraction. It will not fix crashes caused by version mismatches, missing system libraries, or operating system permission restrictions. Use the symptom-based diagnostic approach in this guide before reinstalling to confirm whether reinstallation is actually the appropriate fix.
My antivirus keeps removing Dwarf Therapist after I restore it. What should I do?
Add the entire Dwarf Therapist installation folder to your antivirus exclusion list before extracting the application files. Some antivirus products will quarantine the executable on sight based on
behavioral heuristics related to memory reading. Adding the exclusion first, then extracting the archive into that folder, prevents the antivirus from intercepting the files during extraction.
Dwarf Therapist launches successfully but crashes after a few seconds of use. Is this the same problem?
A crash after a few seconds of use is a different category from a launch crash. This typically indicates a memory layout mismatch that does not trigger immediately but fails when Dwarf Therapist attempts to parse a specific data structure. It can also be caused by the game state changing in a way the layout does not handle. Verify version compatibility and check the GitHub Issues page for reports of this specific behavior in your version pairing.
Does running Dwarf Therapist as administrator on Windows pose any security risk?
Running any application with administrator privileges gives it elevated access to system resources. For a trusted open-source tool like Dwarf Therapist, this is a reasonable tradeoff when necessary. Avoid running applications as administrator as a routine habit without understanding why elevated access is needed.
For Dwarf Therapist specifically, the elevated access is required only to read and write Dwarf Fortress process memory, not to access system-level resources.
Can a corrupted Dwarf Fortress installation cause Dwarf Therapist to crash?
Yes. If the Dwarf Fortress executable itself is corrupted or has been modified in an unexpected way, Dwarf Therapist may crash when attempting to read its memory because the data structures it expects are not present at the anticipated offsets.
Verifying the integrity of your Dwarf Fortress installation, through Steam’s built-in file verification for the Steam version or by re-downloading for the Bay 12 version, eliminates this as a variable.
I have tried everything in this guide and Dwarf Therapist still crashes. What next?
If all standard fixes have been exhausted, building Dwarf Therapist from source for your specific platform and Qt version is the most reliable remaining option. This eliminates binary compatibility issues entirely.
Additionally, check the Dwarf Therapist GitHub repository Issues section and search for your specific crash symptom and platform combination. Other users may have encountered and documented the same issue with a solution that has not yet been incorporated into official documentation.
Latest Post:
