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

# Troubleshoot common issues

## Compile

### The fetch speed is slow when compiling `nativesdk-glibc`

**Resolution**:
Change the source settings as follows:

1. Open the recipe file:
   ```bash theme={null}
    vim <workspace>/layers/poky/meta/recipes-core/glibc/glibc_2.39.bb +35
   ```
2. Add the following line to the file:
   ```cpp theme={null}
    PREMIRRORS = ""
   ```
3. Save the recipe file and exit.
4. Clean and fetch `nativesdk-glibc` again:
   ```bash theme={null}
   bitbake -c cleanall nativesdk-glibc
   bitbake -c do_fetch nativesdk-glibc
   ```
5. After the commands finish, rebuild according to the original procedure.

### Kas reports `remote HEAD refers to nonexistent ref`

**Phenomenon**:
When you run a `kas shell` command, the build fails with the following error even though the layer repository is intact:

```bash theme={null}
ERROR    - warning: remote HEAD refers to nonexistent ref, unable to checkout
```

**Resolution**:
This error is caused by an outdated version of kas. Check your kas version and confirm that it is 4.8 or later:

```bash theme={null}
kas --version
```

If the version is earlier than 4.8, upgrade kas and run the command again.

### eSDK build fails after switching MACHINE in the same workspace

**Phenomenon**:
When you build the eSDK with a different MACHINE in a workspace that was previously used for another MACHINE, the build fails with an error similar to the following:

```bash theme={null}
ERROR: Task (<WORKSPACE>/build/tmp/work/iq_8275_evk-qcom-linux/qcom-robotics-proprietary-image/1.0/sdk-ext/im
age/tmp-renamed-sdk/layers/meta-qcom-robotics-sdk/recipes-products/packagegroups/packagegroup-robotics-opensource.bb:do_populate_lic) failed with
exit code 'setscene ignore_tasks'
NOTE: Tasks Summary: Attempted 12 tasks of which 6 didn't need to be rerun and 1 failed.
```

**Resolution**:
Clean the robotics package group sstate cache, then rebuild the eSDK:

```bash theme={null}
kas shell <YOUR KAS CONFIG> -c "bitbake packagegroup-robotics-proprietary packagegroup-oss-with-prop-deps packagegroup-robotics-opensource -c cleansstate"
```

### Build failed due to network unavailability

**Phenomenon**:
When you build the robotics image, the build fails with an error similar to the following:

```bash theme={null}
ERROR: Task (<WORKSPACE>/build/meta-ros/meta-ros2-jazzy/generated-recipes/rosx-introspection/rosx-introspection_2.3.0-1.bb:do_configure) failed with exit code '1'

ERROR: Task (<WORKSPACE>/build/meta-ros/meta-ros2-jazzy/generated-recipes/foxglove-sdk/foxglove-bridge_3.2.6-1.bb:do_configure) failed with exit code '1'
CMake Error at cmake/CPM.cmake:19 (file):
  file DOWNLOAD cannot compute hash on failed download

    from url: "https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.40.0/CPM.cmake"
    status: [6;"Could not resolve hostname"]
Call Stack (most recent call first):
```

**Resolution**:
To resolve the build failure, add the following code to enable network access for the `do_configure` task in the `rosx-introspection_2.3.0-1.bb` and `foxglove-bridge_3.2.6-1.bb` recipes:

```bash rosx-introspection_2.3.0-1.bb | foxglove-bridge_3.2.6-1.bb theme={null}
 do_configure[network] = "1"
```

## Docker

### Docker is not installed

**Phenomenon**:
Docker is not installed

```bash theme={null}
./scripts/docker_build.sh: line 10: docker: command not found
```

**Resolution**:
Install Docker with the following commands:

```bash theme={null}
sudo apt update
sudo apt install -y docker.io 
```

### Current user is not in the Docker group

**Phenomenon**:
The current user doesn't have permission to access the Docker socket:

```bash theme={null}
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
```

**Resolution**:

1. Add to the Docker group:
   ```bash theme={null}
   sudo usermod -aG docker $USER
   newgrp docker
   # Add your current user to the 'docker' group, so you can run Docker commands without needing sudo
   ```
2. Confirm that you are part of the Docker group:
   ```bash theme={null}
   sudo grep /etc/group -e "docker"
   # This command shows a list of users who are part of the Docker group; must include your user ID
   ```
3. Sign out and sign in again for the access to take effect:
   ```bash theme={null}
   # You can run the following command to check if you are part of the Docker group
   id -a
   # This command returns an output string which should include 'docker'
   ```

### Docker fails to pull images due to network or proxy issues

**Phenomenon**:
Docker cannot reach the remote registry. This is typically due to network restrictions or a missing proxy/mirror configuration:

```bash theme={null}
failed to resolve reference "docker.io/library/ros:jazzy-ros-base-noble": failed to do request: Head "https://registry-1.docker.io/v2/library/ros/manifests/jazzy-ros-base-noble": http: server gave HTTP response to HTTPS client

```

**Resolution**:

Configure a Docker registry mirror that is accessible from your network environment. The following json configuration uses an example Qualcomm registry mirror; replace the URL with a mirror that is appropriate for your network.

<Warning>
  **Warning**

  * Don’t include `#` comments in the JSON configuration file.
  * Using a tab instead of space and other invisible whitespace characters may break the functionality of JSON configuration files and can also lead to `docker.service` failing to start.
</Warning>

1. Open or create the Docker daemon configuration file and add a `registry-mirrors` entry:
   ```bash theme={null}
   sudo vim /etc/docker/daemon.json
   ```
   ```json daemon.json theme={null}
   {
     "registry-mirrors": ["https://<your-registry-mirror>"]
   }
   ```
   Following is an example:
   ```json daemon.json example theme={null}
   {
      "registry-mirrors": ["https://docker-registry.qualcomm.com"]
   }
   ```
2. Restart the Docker service to apply the new settings.

   ```bash theme={null}
   sudo systemctl restart docker
   ```

   <Note>
     **Note**

     For users in China, use an appropriate Docker registry mirror when pulling Docker images.
   </Note>