> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.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
```

***

## High CPU usage overloads the system during build

**When it occurs**: BitBake schedules tasks in parallel and invokes `make` with multiple jobs
to speed up the build. On hosts with limited CPU cores, or when the build runs alongside other
workloads, this can drive CPU usage very high and leave the system unresponsive.

**Solution**: Limit the build's parallelism by setting the `BB_NUMBER_THREADS` and
`PARALLEL_MAKE` variables, as described in the Yocto Project [Limiting the Host Resources
Usage](https://docs.yoctoproject.org/dev-manual/limiting-resources.html) guide. Add these
variables under `local_conf_header` in `meta-qcom/ci/base.yml`:

```yaml meta-qcom/ci/base.yml theme={null}
local_conf_header:
  limit-parallelism: |
    BB_NUMBER_THREADS = "4"
    PARALLEL_MAKE = "-j 4"
```

Adjust the values to match the number of CPU cores you want the build to use, then rerun the
`kas build` command.