Troubleshooting and FAQ
Causes and fixes for the messages you are most likely to meet, followed by common questions. Run any command with --verbose to see the exact tools and command lines WinBridge used.
Building
no supported project found in ...
WinBridge found none of its marker files in the folder you gave it. It looks in that folder only, not in subfolders or parent folders.
Point the command at the folder that holds go.mod, Cargo.toml, the .csproj file, pubspec.yaml or the C sources. The message lists the markers in the order WinBridge checks them.
could not find ... followed by a list of searched folders
The compiler for this project type is not installed, or not where WinBridge looks. The message lists every folder that was searched.
- Go: run
winbridge doctor --install go, or install Go yourself. - C/C++: run
winbridge doctor --install zig, or install MinGW-w64. - Rust: install Rust with
rustup, and the MinGW-w64 linker (gcc-mingw-w64-x86-64on Debian and Ubuntu). - .NET: install the .NET SDK.
winbridge doctor shows the state of every toolchain at once.
winbridge doctor exits with an error although my language works
doctor checks every toolchain and returns exit code 1 if any required tool is missing, including tools for languages you do not use. Read the Toolchains section: only the lines under your toolchain matter to you.
the x86_64-pc-windows-gnu target is not installed
Rust needs the Windows build of its standard library. Add it:
rustup target add x86_64-pc-windows-gnuno direct C/C++ sources found
The folder was recognised as C/C++ because of a CMakeLists.txt or Makefile, but there are no .c or .cpp files in the folder itself or in src/. WinBridge 0.4.0 compiles those files directly and does not run CMake or Make. See Build C and C++ projects.
... is not a Windows PE32+ (x86-64) executable
The compiler finished, but the file it produced did not pass WinBridge's check. Causes include a compiler that built for Linux instead of Windows, and a build with --target windows-arm64: version 0.4.0 accepts only 64-bit x86 output. Build with the default target.
dotnet publish produced no apphost .exe
WinBridge expects a Windows launcher .exe named after the project. Check that UseAppHost is not set to false in the project file.
the Microsoft CRT and Windows SDK are not installed
You asked for --toolchain msvc without the SDK. Either install it with winbridge doctor --install msvc (1–2 GB, under Microsoft's licence), or remove --toolchain msvc to use the default compiler.
no MSVC-compatible linker found
The msvc toolchain needs lld-link, which WinBridge does not download. Install it from your distribution; on Debian and Ubuntu the package is lld.
Running Windows programs
The first run is slow
The first winbridge run downloads the Wine runtime (about 94 MB). The first run of each new app also creates its prefix, which takes a moment. Later runs start directly.
An app does not start or misbehaves
A prefix is disposable. Try again with a clean one:
winbridge prefix delete myapp
winbridge run myapp.exeDeleting the prefix removes that app's settings and saved files inside it. If the app needs an extra runtime, add it with winbridge prefix tricks. Run with --verbose to see Wine's own messages. Whether an app works in the end depends on Wine.
no Vulkan loader found, so DXVK cannot run here
--dxvk needs Vulkan. Install your distribution's Vulkan loader and the Vulkan driver for your graphics card, then check the vulkan line in winbridge doctor.
A script waits a few seconds after the app has finished
Wine keeps a background process per prefix for a few seconds after an app exits, so that the next start is quick. winbridge run itself returns as soon as your app exits. A tool that waits for the output pipe to close, not for the command to end, can appear to pause briefly.
A launcher entry does nothing
Entries made by winbridge desktop add call winbridge by name. If you installed from the tarball, make sure ~/.local/bin is on the PATH of your desktop session, then sign out and in again.
Packaging
no built artifacts at ...
winbridge package looks in build/winbridge/windows-x64 inside the project. Run winbridge build first, or point --artifacts at the folder that holds your built files.
osslsigncode is not installed, so the installer was not signed
Install osslsigncode from your distribution and run the command again. To build without a signature, remove --sign.
The Windows VM
no VM config at ...
WinBridge has no connection details for the VM. Create ~/.config/winbridge/vm.json as described in Build Flutter apps on a Windows VM.
Host key verification failed
On the first connection, SSH does not know the VM yet. Run winbridge vm doctor --accept-new once.
If the message says the host identification has changed, and you rebuilt the VM, the key really is new. Remove the old entry from ~/.ssh/known_hosts (the SSH message names the line), then run winbridge vm doctor --accept-new. If you did not rebuild the VM, stop and find out why the key changed. WinBridge has no option to switch host key checking off.
MISSING remote flutter
flutter is not on the PATH of the VM's SSH session. Run setup-windows.ps1 again in the VM, or set flutterPath in vm.json to the full path of flutter.bat.
The Flutter build fails on the VM with Visual Studio or CMake errors
Run flutter doctor -v inside the VM. It names what is missing. Most often the C++ workload is not installed: run setup-windows.ps1 again, or open Visual Studio Installer, choose Modify, and select Desktop development with C++.
The VM does not accept SSH connections
setup-windows.ps1 opens port 22 in the Windows firewall. If you changed the SSH port or created the VM another way, check the inbound rules in Windows Defender Firewall yourself.
Copying the project to the VM is very slow
WinBridge leaves out build/, .dart_tool/ and .git/. Other large folders in the project are copied. Move big files that the build does not need out of the project folder.
Questions
Does WinBridge run on Windows or macOS?
No. WinBridge is a Linux program. Version 0.4.0 is released for 64-bit x86 Linux.
Do I need Windows at all?
Not for Go, Rust, .NET or C/C++ projects. Flutter apps need a Windows VM, because flutter build windows only runs on Windows.
Does WinBridge need sudo?
Only to install its own .deb package, and for compilers you choose to install from your distribution. Everything WinBridge downloads itself goes into your home folder.
Does WinBridge send any data anywhere?
WinBridge contacts the network to download the components you ask for, to reach your own VM, and to reach a timestamp server when you sign an installer. winbridge report prints its report to your terminal and sends nothing.
Which apps are known to work under winbridge run?
The project keeps a short compatibility list in its repository, built from reports. So far it covers the project's own test program. For any other app, try it; a prefix is cheap to delete.
How do I free disk space?
Delete ~/.cache/winbridge. Compilers and runtimes are downloaded again when you next need them. App prefixes in ~/.local/share/winbridge/prefixes/ are not a cache: remove them one by one with winbridge prefix delete.
Where do I report a problem?
On the GitHub issues page. Include the output of winbridge report; it leaves out your host name, user name and home folder paths.