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

# 排查常见问题

## 编译

### 编译 `nativesdk-glibc` 时获取速度慢

**解决方法**：
按如下方式修改源设置：

1. 打开 recipe 文件：
   ```bash theme={null}
    vim <workspace>/layers/poky/meta/recipes-core/glibc/glibc_2.39.bb +35
   ```
2. 在文件中添加以下行：
   ```cpp theme={null}
    PREMIRRORS = ""
   ```
3. 保存 recipe 文件并退出。
4. 再次清理并获取 `nativesdk-glibc`：
   ```bash theme={null}
   bitbake -c cleanall nativesdk-glibc
   bitbake -c do_fetch nativesdk-glibc
   ```
5. 命令执行完成后，按照原有流程重新构建。

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

**现象**：
运行 `kas shell` 命令时，即使 layer 仓库完好无损，构建仍会失败并出现以下错误：

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

**解决方法**：
此错误由过旧的 kas 版本导致。检查你的 kas 版本，确认其为 4.8 或更高版本：

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

如果版本低于 4.8，请升级 kas 并重新运行该命令。

### 在同一工作区中切换 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.
```

**解决方法**：
清理 robotics 包组的 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"
```

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

**现象**：
构建 robotics 镜像时，构建失败并出现类似以下的错误：

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

**解决方法**：
要解决此构建失败问题，请在 `rosx-introspection_2.3.0-1.bb` 和 `foxglove-bridge_3.2.6-1.bb` recipe 中添加以下代码，为 `do_configure` 任务启用网络访问：

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

## Docker

### 未安装 Docker

**现象**：
未安装 Docker

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

**解决方法**：
使用以下命令安装 Docker：

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

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

**现象**：
当前用户没有访问 Docker socket 的权限：

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

**解决方法**：

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

### 由于网络或代理问题 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

```

**解决方法**：

配置一个在你的网络环境中可访问的 Docker 镜像仓库镜像（registry mirror）。以下 json 配置使用了一个 Qualcomm 镜像仓库示例；请将该 URL 替换为适合你网络环境的镜像地址。

<Warning>
  **警告**

  * 不要在 JSON 配置文件中包含 `#` 注释。
  * 使用制表符（Tab）代替空格以及其他不可见的空白字符可能会破坏 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>