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

# 常见问题故障排除

## 编译

### 编译 `nativesdk-glibc` 时下载速度慢

<Accordion title="解决方案">
  按如下方式更改源设置:

  1. 打开配方文件:
     ```bash theme={null}
      vim <workspace>/layers/poky/meta/recipes-core/glibc/glibc_2.39.bb +35
     ```
  2. 在该文件中添加以下行:
     ```text theme={null}
      PREMIRRORS = ""
     ```
  3. 保存配方文件并退出。
  4. 清理并再次获取 `nativesdk-glibc`:
     ```bash theme={null}
     bitbake -c cleanall nativesdk-glibc
     bitbake -c do_fetch nativesdk-glibc
     ```
  5. 命令完成后,按原始步骤重新构建。
</Accordion>

### Kas 报告 `remote HEAD refers to nonexistent ref`

**现象**:
运行 `kas shell` 命令时,即使层存储库完好无损,构建也会失败并显示以下错误:

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

<Accordion title="解决方案">
  此错误由过时版本的 kas 引起。检查您的 kas 版本并确认其为 4.8 或更高版本:

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

  如果版本低于 4.8,请升级 kas 并再次运行命令。
</Accordion>

### 由于缺少 Perl 模块依赖项导致 eSDK 安装失败

**现象**:
运行 eSDK 安装脚本时,安装失败并显示以下错误:

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

**解决方案**:
此错误在主机上的 `perl-modules` 软件包缺失或不完整时发生。请重新安装该软件包,然后再次运行安装程序:

1. 打开一个新终端。不要在此终端中 source eSDK 环境设置脚本。
2. 查找可用于您主机的 `perl-modules` 版本:
   ```bash theme={null}
   sudo apt update
   apt search perl-modules
   ```
3. 重新安装该软件包。将 `<VERSION>` 替换为上一步返回的版本:
   ```bash theme={null}
   sudo apt install --reinstall perl-modules-<VERSION>
   ```
4. 确认 `FindBin` 模块已加载:
   ```bash theme={null}
   perl -MFindBin -e 'print "FindBin OK\n"'
   ```
   模块可用时,该命令打印 `FindBin OK`。
5. 从包含 eSDK 安装程序的目录再次运行它:
   ```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. 使用 `devtool` 构建机器人镜像:
   ```bash theme={null}
   cd ~/qcom-robotics-ros2-jazzy_sdk
   . environment-setup-armv8-2a-qcom-linux
   devtool build-image qcom-robotics-proprietary-image
   ```

### 在同一工作区切换 MACHINE 后 eSDK 构建失败

**现象**:
当您在先前用于另一个 MACHINE 的工作区中使用不同的 MACHINE 构建 eSDK 时,构建会失败并显示类似以下的错误:

```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="解决方案">
  清理机器人软件包组 sstate 缓存,然后重新构建 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>

### 由于网络不可用导致构建失败

**现象**:
当您构建机器人镜像时,构建失败并显示类似以下的错误:

```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="解决方案">
  要解决构建失败,请添加以下代码,以便在 `rosx-introspection_2.3.0-1.bb` 和 `foxglove-bridge_3.2.6-1.bb` 配方中为 `do_configure` 任务启用网络访问:

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

## Docker

### 未安装 Docker

**现象**:
未安装 Docker

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

<Accordion title="解决方案">
  使用以下命令安装 Docker:

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

### 当前用户不在 Docker 组中

**现象**:
当前用户没有权限访问 Docker 套接字:

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

<Accordion title="解决方案">
  1. 添加到 Docker 组:
     ```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. 确认您已加入 Docker 组:
     ```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. 注销并重新登录以使访问生效:
     ```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 由于网络或代理问题无法拉取镜像

**现象**:
Docker 无法访问远程注册表。这通常是由于网络限制或缺少代理/镜像配置所致:

```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="解决方案">
  配置一个可从您的网络环境访问的 Docker 注册表镜像。以下 JSON 配置使用一个示例 Qualcomm 注册表镜像;请将 URL 替换为适合您网络的镜像。

  <Warning>
    **警告**

    * 不要在 JSON 配置文件中包含 `#` 注释。
    * 使用制表符代替空格以及其他不可见的空白字符,可能会破坏 JSON 配置文件的功能,还可能导致 `docker.service` 无法启动。
  </Warning>

  1. 打开或创建 Docker 守护进程配置文件,并添加一个 `registry-mirrors` 条目:
     ```bash theme={null}
     sudo vim /etc/docker/daemon.json
     ```
     ```json daemon.json theme={null}
     {
       "registry-mirrors": ["https://<your-registry-mirror>"]
     }
     ```
     下面是一个示例:
     ```json daemon.json example theme={null}
     {
        "registry-mirrors": ["https://docker-registry.qualcomm.com"]
     }
     ```
  2. 重启 Docker 服务以应用新设置。

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

       <Note>
         **注意**

         对于中国用户,拉取 Docker 镜像时请使用适当的 Docker 注册表镜像。
       </Note>
</Accordion>