> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Yocto Builds

This page documents common errors encountered during Yocto builds on Qualcomm Linux
and their solutions.

## Missing `en_US.UTF-8` locale

**When it occurs**: This issue is common on minimal Ubuntu installations, including
base WSL2 images (Ubuntu 22.04), which ship with only the `C.UTF-8` locale by default.
BitBake requires the `en_US.UTF-8` locale and fails immediately at startup if it is
not present.

**Error message**:

```
Please make sure locale 'en_US.UTF-8' is available on your system
```

**Solution**: Generate and enable the `en_US.UTF-8` locale before running any `kas`
or `bitbake` command.

```bash theme={null}
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8
```

After running these commands, open a new shell session so the updated
locale settings take effect, then retry the build.

***

## Restrictive `umask` causes build failures

**When it occurs**: If your shell session is configured with a restrictive `umask`
(such as `0027` or `0077`), OE-core's sanity checker rejects the configuration
before the build starts.

**Error message**:

```
ERROR:  OE-core's config sanity checker detected a potential misconfiguration.
    Either fix the cause of this error or at your own risk disable the checker (see sanity.conf).
    Following is the list of potential problems / advisories:

    Please use a umask which allows a+rx and u+rwx
```

**Solution**: Set `umask 022` in your shell before starting the build. This ensures
Yocto-created files are world-readable, which is required for the build system to
function correctly.

```bash theme={null}
umask 022
```

To make this persistent for your build sessions, add it to your shell startup file:

```bash theme={null}
echo 'umask 022' >> ~/.bashrc
source ~/.bashrc
```