Smash Ultimate PC troubleshooting

Match the symptom

Build and startup

OpenSmash asks for unexpected Build Tools

A prebuilt runtime works only with the matching source. Read the rejection reason immediately above the error. An older/newer source copy, incomplete files or a failed runtime download can force another build path. Reopen the current source installer before adding a manual runtime ZIP.

OpenSmash says a game DLL is missing

Close the game, reopen Install SSBU.bat and use Resume. The installer can relink missing output. If Windows Security recorded removal of a file, inspect that record and the file’s origin before deciding what to restore. Keep security decisions specific to the reported file.

The game build is unknown or incomplete

OpenSmash recognises only its supported game versions. Check game versions and existing layouts, including main.npdm, instead of mixing another version’s files into the folder.

For WindowSmash Windows, check AVX2/FMA/F16C and its DirectX 11 driver. Its installer records checks in install.log. On Mac, check Apple silicon and the required Apple tools before retrying the build.

Black opening and graphics

OpenSmash Windows movie stays black

Look for MFCreateSourceReaderFromByteStream, a missing Vorbis decoder or no FFmpeg DLLs. Reopen the installer so it can restore its media dependency path. If the failure persists, attach the decoder messages with the run log.

Linux window is black

1. Open a terminal in the environment where you launch the game; for OpenSmash on SteamOS, enter the ssbu distrobox first.
2. Run vulkaninfo --summary.
3. Check whether it lists your intended hardware GPU.

WindowSmash Linux: its renderer goes through DXVK. If the intended GPU is listed but the window stays black, launch once more and keep the DXVK/cannot create the window error text, build/play.log, and the matching text report in reports/. On distributions that use that package name, mesa-vulkan-drivers is the Mesa-driver check for AMD/Intel. For NVIDIA, use its matching Vulkan driver.

OpenSmash Linux: after shader preparation has finished, launch once more and inspect nvn_vk: lines in the terminal or the actual XDG run log listed below. Run bash scripts/linux/collect_logs_linux.sh from the source directory and keep the report path it prints. If no frame appears for more than five seconds, include build-linux/work/ssbu_native_freeze.txt if created. Report those errors with the GPU/driver output if the window still stays black.

Freezes, saves and performance

WindowSmash freezes or stutters

A first-use shader can briefly delay an effect. On Windows, let Prepare Shaders finish. For persistent low frame rate, check the actual GPU in use and whether shader compilation is still running.

A freeze with no new picture for five seconds creates a report in reports/. Keep build/play.log and the matching text report. Include both files when reporting the freeze.

OpenSmash Linux runs out of build memory

Reduce --jobs N in the same setup command and resume it. Keep --dump when rerunning the Linux build. Do not start another parallel build while memory is already exhausted.

Save progress looks wrong

In WindowSmash, check the launcher’s chosen game version and that version’s save/. In OpenSmash, check the remembered Install location on Windows or the Linux userdata path. Follow save migration and backup before replacing anything.

Report an issue

OpenSmash's --userdata option changes saves, not the play.sh log path. Read XDG_DATA_HOME in the same environment you used to launch; for SteamOS that means inside the container.

Send the text report and log through the relevant project’s issue page. Check them for personal paths or names before posting. WindowSmash minidumps contain memory; share those privately if requested.

If the symptom is a missing online room, compare the lobby and game version using online checks before filing it. For an input issue, include the adapter mode, driver and project from controls.

Versions covered by this guide

Back to top