> ## 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.

# Troubleshoot common issues

## Compile

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

<Accordion title="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:
     ```text 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.
</Accordion>

### 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
```

<Accordion title="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.
</Accordion>

### eSDK installation fails due to missing Perl module dependencies

**Phenomenon**:
When you run the eSDK installer script, the installation fails with the following error:

```bash theme={null}
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: 

Required perl module(s) not found: open ':std' FindBin
```

**Resolution**:
This error occurs when the `perl-modules` package on the host is missing or incomplete. Reinstall the package, then run the installer again:

1. Open a new terminal. Don't source the eSDK environment setup script in this terminal.
2. Find the `perl-modules` version that is available for your host:
   ```bash theme={null}
   sudo apt update
   apt search perl-modules
   ```
3. Reinstall the package. Replace `<VERSION>` with the version returned in the previous step:
   ```bash theme={null}
   sudo apt install --reinstall perl-modules-<VERSION>
   ```
4. Confirm that the `FindBin` module loads:
   ```bash theme={null}
   perl -MFindBin -e 'print "FindBin OK\n"'
   ```
   The command prints `FindBin OK` when the module is available.
5. Run the eSDK installer again from the directory that contains it:
   ```shell theme={null}
   cd <decompressed_workspace>/images/<machine>/sdk
   umask a+rx
   sh ./qcom-robotics-ros2-jazzy-x86_64-qcom-robotics-proprietary-image-armv8-2a-iq-9075-evk-toolchain-ext-2.8.0.sh
   ```
6. Build the robotics image with `devtool`:
   ```bash theme={null}
   cd ~/qcom-robotics-ros2-jazzy_sdk
   . environment-setup-armv8-2a-qcom-linux
   devtool build-image qcom-robotics-proprietary-image
   ```

### 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.
```

<Accordion title="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"
  ```
</Accordion>

### 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):
```

<Accordion title="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"
  ```
</Accordion>

## Docker

### Docker is not installed

**Phenomenon**:
Docker is not installed

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

<Accordion title="Resolution">
  Install Docker with the following commands:

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

### 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
```

<Accordion title="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'
     ```
</Accordion>

### 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

```

<Accordion title="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>
</Accordion>