# Troubleshooting melange builds

URL: https://chainguard-docs-preview-git-fix-ai-metadata-year.chainguard.app/open-source/build-tools/melange/troubleshooting.md
Last Modified: September 28, 2026
Tags: melange, Troubleshooting

Debugging and common errors with melange build


## Debug options

To include debug-level information on melange builds, edit your `melange.yaml` file and include `set -x` in your pipeline. You can add this flag at any point of your pipeline commands to further debug a specific section of your build.

```yaml
...
pipeline:
  - name: Build Minicli application
    runs: |
      set -x
      APP_HOME="${{targets.destdir}}/usr/share/hello-minicli"
...
```

## Common errors

When melange is unable to finish a build successfully, you will get an error similar to this:

> **Danger**: Error: failed to build package: unable to run pipeline: exit status 127


The build could not be completed due to an error at some point of your pipeline. Enable debug by including `set -x` at the beginning of your build pipeline so that you can nail down where the issue occurs.

### Missing QEMU user-space emulation packages

Linux users using the Docker melange image may get errors when building packages for other architectures than `x86` and `x86_64`. This won't happen for Docker Desktop users, since the additional architectures are automatically enabled upon installation.

To enable additional architectures, you'll need to enable them within your kernel with the following command:

```shell
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```

An alternate approach to achieve the same result is to run the following command:

```shell
docker run --privileged --rm tonistiigi/binfmt --install all
```

### Missing build-time dependencies

You may get errors from missing build-time dependences such as `busybox`. In this case you may get "No such file or directory" errors when enabling debug with `set -x`. To fix this, you'll need to locate which package has the commands that your build needs, and add it to the list of your build-time dependencies.

## Further resources

For additional guidance, please refer to the [melange repository](https://github.com/chainguard-dev/melange) on GitHub, where you can find [more examples](https://github.com/chainguard-dev/melange/tree/main/examples) or [open an issue](https://github.com/chainguard-dev/melange/issues/new/choose) in case of problems.