Troubleshooting Wine and Proton

A systematic workflow for diagnosing Wine/Proton issues, from quick health checks to detailed log analysis, and from common failures to community resources.

Diagnostic Workflow#

graph TD
    A["程序/游戏无法运行"] --> B{"有错误提示吗？"}
    B -->|有| C["根据错误信息定位"]
    B -->|无| D["生成 PROTON_LOG"]
    D --> E["查看日志尾部错误"]
    C --> F{"错误类型？"}
    F -->|Vulkan| G["检查显卡驱动"]
    F -->|DLL/missing| H["安装缺失组件"]
    F -->|crash/segfault| I["检查系统库"]
    G --> J{"vulkaninfo 正常？"}
    J -->|否| K["核对驱动/loader/位宽与实际环境"]
    J -->|是| L["检查 max_map_count"]
    H --> M["winetricks / protontricks"]
    I --> N["检查 ldd / steam-runtime"]
    L --> O["有耗尽证据时评估目标值与回滚"]

Step 1: System Health Check

# 1. 确认 Vulkan 正常工作
vulkaninfo --summary 2>&1 | grep -E "GPU|deviceName|apiVersion"

# 2. 确认 OpenGL 正常
glxinfo | grep "OpenGL version"

# 3. 确认显卡驱动加载
lsmod | grep -E "nvidia|amdgpu"

# 4. 检查 max_map_count
cat /proc/sys/vm/max_map_count
# 记录当前值；仅在日志和应用要求表明不足时评估调整。

# 5. 检查是否有 NTSYNC 支持
ls -l /dev/ntsync
# 节点缺失也可能是内核配置、模块或设备策略问题；存在不等于当前程序使用。

Common Problems and Fixes#

A Game or Application Will Not Start

Symptoms: clicking Launch does nothing, or the application crashes immediately.

Troubleshooting steps:

# Steam 游戏：生成日志
PROTON_LOG=1 %command%
# 日志生成在 ~/steam-<APPID>.log

# 非 Steam：命令行启动观察输出
WINEDEBUG=+loaddll wine myapp.exe 2>&1 | tail -50

Common fixes:

• Keep the old runner and a prefix backup, then test an official numbered stable release, Experimental, or a GE version suited to the game. Avoid changing several conditions at once
• Rebuild the prefix only if you suspect its state is corrupted: first exit the application, back up saves and activation/license state, and rename the compatdata directory. Do not delete the only copy
• Verify game-file integrity (Steam Properties → Local Files)

Vulkan Initialization Fails

Symptoms: errors mentioning winevulkan, vkCreateInstance failed, or missing extensions/symbols.

Possible causes: mismatched drivers, Vulkan loader, ICD, graphics-component versions, or 32/64-bit libraries; differences inside and outside Flatpak; incorrect GPU selection on a hybrid system; or hardware that genuinely lacks a required extension. A single error string is not enough to identify the cause.

First confirm devices and versions in the actual launch environment, then check the project's package sources. The AMD/Mesa example on Arch requires the appropriate repositories and multilib. Avoid partial upgrades or mixing in incompatible libraries from another channel:

# Arch 示例：需符合该系统的完整升级策略，不能在 NixOS 上执行。
sudo pacman -Syu vulkan-radeon lib32-vulkan-radeon mesa lib32-mesa

NixOS uses declarative graphics configuration. Enable 32-bit support according to the actual requirements of Steam and the runner:

hardware.graphics = {
  enable = true;
  enable32Bit = true;
};

This fragment does not mean a build or activation has already been performed. For NVIDIA, check the relevant driver configuration separately; the AMD package list is not a substitute. For Flatpak, check matching runtime GL extensions and application permissions. Passing host-side tests does not mean a Bottle has passed them.

Black Screens in Cutscenes or Video

Symptoms: the title screen works, but a particular video shows a black screen, color bars, or no audio.

Possible causes involve Media Foundation, GStreamer, codecs, media conversion, GPU decoding, or game-specific fixes. Record the scene and logs first, then check how the selected Proton version handles that game's media issues:

1. Check the fix status in official Proton and game issues, then back up the prefix before comparing versions.
2. Some GE versions carry additional media fixes and can serve as a comparison, but they do not guarantee playback of every video.
3. Do not assume mf-install is a built-in verb in current protontricks/winetricks. First check the component list and the external project's source, license, and compatibility requirements.
4. The PROTON_ENABLE_MEDIACONV variable mentioned in the source material requires checking against the specific build. It is not a fix switch recognized by all current Proton versions; setting an invalid variable usually produces no error either.

protontricks <APPID> list-installed
# 具体依赖安装应依据目标版本的列表和日志，而不是批量注入全部 DLL。

Record changes before and after installing components so that a media issue does not become a DLL conflict.

Anti-cheat (EAC/BattlEye) Does Not Work

Symptoms: a multiplayer game reports that anti-cheat is not running, or the server refuses the connection.

Support depends on the Proton/Linux path enabled by the game developer, the specific anti-cheat integration, the game version, and service policies. Supported paths in some EAC/BattlEye integrations do not mean every game using them will work. Wine or GE cannot bypass kernel anti-cheat or account policies.

• Check the game's official support information, Steam/Proton issues, and current status first, then consult community records on ProtonDB or Are We Anti-Cheat Yet.
• Steam-provided anti-cheat runtimes and the game installation must be intact. If the developer has not enabled compatibility support, switching to GE or specifying a runtime path will not automatically solve the problem.
• The PROTON_EAC_RUNTIME/PROTON_BATTLEYE_RUNTIME variables in the source material are internal/build-specific path mechanisms, not universal launch templates for every game.
• Do not use bypasses, DLL replacements, or patches of unknown origin to evade service policies. Successful single-player startup does not prove multiplayer service access is allowed.

When reporting a problem, record the runner, game version, errors, and official support limits. Do not provide account or authentication information.

Audio Crackling or Synchronization Drift

Symptoms: audio cuts out, crackles, or gradually drifts out of sync with video. Possible causes include buffers, CPU scheduling, device clocks, the runner's audio implementation, or system audio configuration.

First record the current PipeWire quantum/rate and CPU load. Lowering the quantum reduces latency but may increase xruns; it is not a universal fix for crackling. If comparison is genuinely needed, the following examples show temporary settings and how to undo them:

pw-metadata -n settings 0 clock.force-quantum 256
# 对照完成后解除强制值，恢复自适应策略。
pw-metadata -n settings 0 clock.force-quantum 0
ulimit -e

Test the defaults and larger/smaller buffers before deciding whether persistent configuration is needed. On NixOS, manage PAM/service resource limits through the appropriate Nix modules rather than editing the managed /etc/security/limits.conf directly. Joining the audio group or setting a nice limit does not automatically prove real-time scheduling is active.

Missing or Garbled Chinese Text

Distinguish missing-glyph boxes from character-encoding errors and input-method problems. Check the application's actual font, host font coverage, fonts inside the prefix, and locale first, rather than attributing every issue to one DLL.

# 独立普通 Wine Prefix 的候选字体依赖；按应用需要与许可核对。
WINEPREFIX="$HOME/Games/MyTool" winetricks cjkfonts
# 宿主字体查询只证明宿主字体集，不证明沙箱字体可见。
fc-list :lang=zh

Bottles uses its own dependency or import mechanisms; also check which fonts are visible inside the specific Bottle. Do not assume a Flatpak override for /usr/share/fonts is required or guaranteed to work. That directory is subject to sandbox reserved-path and font-integration rules.

If you clearly have permission to use and copy a font, you can install the specific files into the font directory of a stopped prefix, then verify them through the corresponding runner's font registration and an application test:

cp -- "$HOME/Fonts/ExampleFont.ttf" \
  "$HOME/Games/MyTool/drive_c/windows/Fonts/"

Avoid copying all host fonts with a wildcard, overwriting unknown files, or treating a font cache as proof that the runtime problem is solved.

Games on an NTFS Partition Will Not Start

Symptoms: Steam games stored on a Windows NTFS partition fail to launch through Proton.

Causes: behavior depends on the NTFS driver, mount options, permission mapping, symbolic links, and filename semantics. Windows hibernation/Fast Startup may also cause read-only or state problems. The filesystem name alone does not establish that every failure has the same cause.

Troubleshooting: check mounts and file permissions first, then compare against a separate Steam library and compatdata on a native Linux filesystem. Sharing one library between Windows and Linux adds consistency and launcher risks; in particular, avoid sharing the same mutable Prefix. Preserve saves and game files before migration. Deleting the library should not be the first step.

Analyzing PROTON_LOG Output#

Generate and Use Logs

PROTON_LOG=1 %command%
# 日志：~/steam-<APPID>.log

Common Log Patterns

Key Log Levels

WINEDEBUG=+timestamp,+seh,+loaddll  # 时间戳 + 异常 + DLL 加载
WINEDEBUG=+ntsync                   # 仅对实现该通道的 runner，结果是线索而非完整使用证明
PROTON_LOG=1                        # Proton 的便捷调试日志，不保证包含所有诊断

Community Resources#

Logs may contain usernames, paths, launch arguments, or account information. Redact them before publishing, and do not copy tokens, private keys, internal addresses, or complete environment variables. All troubleshooting commands in this article are examples; none was executed during this edit.

Sources and Verification Limits#

The following references define the relevant mechanisms and support boundaries. Installation, builds, activation, prefix state, and actual application behavior must each be verified in the target environment. The example commands do not establish successful execution on any host.

• Official Proton README
• GE-Proton README
• Linux NTSYNC Interface
• Flatpak Sandbox Permissions
• Winetricks Upstream
• Protontricks Upstream
• ProtonDB (Community Reports)
• WineHQ AppDB (Compatibility Reports)
• Arch Wiki: Wine (Third-party Distribution Reference)
• Are We Anti-Cheat Yet (Community Tracking)