> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bach builds Windows installers from one bach.toml with the bach command: bach init, bach check, bach preview, bach build. Installs are per user and need no administrator rights by default. installer.scope = "machine" installs for every user after one Windows prompt. On Windows, run setup files with Start-Process -Wait -PassThru in PowerShell, and give signtool arguments that start with the word sign.

# Troubleshooting Bach: common messages and how to fix them

> Fix the messages people meet most when installing bach, building a setup file or running one: runtime download, missing files, symlinks, locked files and downgrades.

Bach reports every mistake as one sentence that names the thing at fault. This page lists the messages people meet most and what to do about each. Start with `bach doctor`: it says exactly what is missing.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
bach doctor
```

## When building

> [accordion] couldn't get bach-setup.exe ...
>
> There is no network, or there is no release for this version. Put `bach-setup.exe` next to `bach`, or pass `--runtime PATH`, or set `BACH_RUNTIME`. Download the zip from the [releases page](https://github.com/usebach/bach/releases) if you need the file. If `BACH_NO_DOWNLOAD` is set, `bach` never downloads it. See [Install Bach](/docs/installation.md).

> [accordion] app.executable is "...", but there is no such file
>
> Build your app first, or fix `[files] source` and `[app] executable`. Both are relative: `source` is relative to `bach.toml`, and `executable` is relative to `source`.

> [accordion] ... is a symbolic link
>
> The source folder cannot contain symbolic links. Copy real files into it.

> [accordion] couldn't replace ... (is it open?)
>
> Close the old setup file or the running app, then build again.

> [accordion] bach preview ... needs Windows
>
> Preview needs Windows. Use `bach check` on macOS and Linux.

> [accordion] requirements\[0]. ...
>
> Give `kind` one of `webview2`, `dotnet`, `vcredist`, `file` or `registry`. `file` and `registry` need a `name` and an https `url`. See [`[[requirements]]`](/docs/reference/config/requirements).

> [accordion] A warning about a text given in one language
>
> A `[text]` entry exists in only one language while the window speaks several. Add the other languages or limit `installer.languages`.

> [accordion] The setup file shows Bach's icon
>
> On macOS and Linux, `app.icon` is not applied. Build on Windows.

## When installing

> [accordion] The installer says a newer version is installed
>
> Raise `version` above the installed one, or pass `--allow-downgrade` on a silent run.

> [accordion] The installer says the app is still open
>
> Close the app and press "Try again", or press "Close and continue" to ask the app to close the way Windows Update does.

> [accordion] A requirement page appears
>
> Install what it names with the button, then press "Try again". A silent install exits with code `1` instead.

> [accordion] The disk is full
>
> The window names the needed and free space. Free up room or install to another drive with the Location row, or `--dir` on a silent run.

> [accordion] Windows SmartScreen warns about the download
>
> The setup file is unsigned or the publisher is new. [Sign the file](/docs/guides/signing.md).

## When installing Bach itself

> [accordion] npm install says 404 Not Found for @usebach/cli
>
> A package that was published only minutes ago can take a few minutes to appear everywhere. Wait and try again. If it still fails, check `npm config get registry` (it should be `https://registry.npmjs.org/`) and your proxy or company registry, then try the install script from [Install Bach](/docs/installation.md).

> [accordion] The bach program for ... isn't installed
>
> npm ran with `--omit=optional` (or `--no-optional`) and skipped the platform package that holds the program. Install again without that flag: `npm install --global @usebach/cli`.

> [accordion] npm install fails with EACCES or permission denied
>
> Do not use `sudo`. Give npm a global folder of your own once, add its `bin` folder to your `PATH`, and install again: `npm config set prefix ~/.npm-global`.

> [accordion] bach is found, but it's an older version
>
> Another copy comes first on your `PATH`, for example one from `install.ps1`. Run `where bach` (Windows) or `which -a bach` to see them, and remove the one you don't want. `npm uninstall --global @usebach/cli` removes the npm copy.

> [accordion] install.ps1 refuses a folder
>
> It never writes into a folder it did not create. Set `BACH_INSTALL_DIR` to an empty folder.

> [accordion] install.ps1 cannot replace a file
>
> Close any running `bach`, then run the script again.

> [accordion] bach is not found after installing
>
> Open a new terminal. The script adds its folder to your user `PATH`, which only new terminals see. In the same terminal, call it by its full path.

> [accordion] The download does not match its SHA-256
>
> Nothing was installed. Check your connection and try again, or use the zip from the releases page.

## Read the log

Every setup run writes `%TEMP%\<app id>-setup.log`, or the file you pass with `--log`. It names the steps and, when something fails, why. Read it instead of guessing, and attach it to a bug report.

## Still stuck?

Open a [bug report](https://github.com/usebach/bach/issues/new?template=bug_report.yml) with a small `bach.toml` that shows the problem, the output of `bach doctor`, and the setup log. See [Support](https://github.com/usebach/bach/blob/main/SUPPORT.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.