nerdctl错误代码速查：常见问题诊断与解决手册
项目地址: https://gitcode.com/gh_mirrors/ne/nerdctl 前言：nerdctl错误处理机制
nerdctl作为containerd的Docker兼容命令行工具（Containerd-compatible CLI），采用分层错误处理架构。核心错误处理逻辑位于pkg/errutil/exit_coder.go，通过ExitCoder接口实现错误码标准化传递：
type ExitCoder interface {
error
ExitCode() int // 标准化错误退出码
}
// 典型错误传播路径
func HandleExitCoder(err error) {
if exitErr, ok := err.(ExitCoder); ok {
os.Exit(exitErr.ExitCode())
}
}
错误码体系分为三类：
- 标准POSIX错误码（1-127）：遵循UNIX系统调用规范
- 应用自定义错误码（128-255）： nerdctl扩展错误空间
- 嵌套错误：通过
errors.Is()和errors.As()实现错误链解析
一、连接与通信错误（1xx系列）
1.1 连接拒绝错误（错误码111）
错误特征：connection refused 或 IsErrConnectionRefused判断为真
// 错误检测逻辑（pkg/errutil/errors_check.go）
func IsErrConnectionRefused(err error) bool {
return strings.Contains(err.Error(), "connection refused")
}
常见场景与解决方案：
| 错误场景 | 排查步骤 | 解决方案 |
|---|---|---|
| containerd服务未启动 | systemctl status containerd | systemctl start containerd |
| 错误的socket路径 | 检查--address参数 | 正确路径： - 根用户： /run/containerd/containerd.sock- 非根用户： $XDG_RUNTIME_DIR/containerd-rootless/containerd.sock |
| 权限不足 | 验证socket文件权限 | sudo chmod 666 /run/containerd/containerd.sock（临时方案）或使用rootless模式 |
| 防火墙拦截 | iptables -L INPUT -n | 添加规则：iptables -A INPUT -p unix -j ACCEPT |
错误流程图：
1.2 命名空间访问错误（错误码125）
典型错误信息：
FATA[0000] failed to list containers: namespace "k8s.io" not found
解决方案：
- 查看可用命名空间：
nerdctl namespace ls - 切换命名空间：
nerdctl --namespace=k8s.io ps - k3s环境特殊处理：
nerdctl --address=/run/k3s/containerd/containerd.sock --namespace=k8s.io ps
二、容器生命周期错误（2xx系列）
2.1 容器状态错误（错误码255）
错误特征：操作与容器当前状态冲突，如停止已停止的容器
状态转换矩阵：
| 当前状态 | 允许操作 | 禁止操作（错误码255） |
|---|---|---|
| created | start, rm | stop, pause, exec |
| running | stop, pause, exec, rm | start |
| paused | unpause, stop | start, exec |
| stopped | start, rm | stop, pause |
诊断命令：
# 查看容器详细状态
nerdctl inspect --mode=native <container_id> | jq .Status.Status
2.2 端口映射失败（错误码200）
常见错误信息：
FATA[0000] failed to publish ports: listen tcp 0.0.0.0:8080: bind: address already in use
解决方案：
- 端口冲突检测：
# 查找占用进程
ss -tulpn | grep 8080
# 或使用nerdctl自带工具
nerdctl port ls
-
解决方法：
- 更换端口：
nerdctl run -p 8081:80 nginx - 终止占用进程：
kill -9 <PID> - 强制释放端口（Linux）：
ss -K tcp dport = :8080
- 更换端口：
-
Rootless模式特殊处理：
- 低端口限制：非root用户无法绑定<1024端口
- 解决方案：
sudo sysctl net.ipv4.ip_unprivileged_port_start=0
三、镜像操作错误（3xx系列）
3.1 镜像拉取失败（错误码301-305）
错误码301：仓库访问拒绝
FATA[0000] failed to pull image: failed to resolve reference "example.com/nginx:latest": failed to do request: Head "https://example.com/v2/nginx/manifests/latest": dial tcp: lookup example.com on 8.8.8.8:53: no such host
排查流程：
非HTTPS仓库配置：
# /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."example.com:5000"]
endpoint = ["http://example.com:5000"]
3.2 镜像格式错误（错误码310）
错误信息：
FATA[0000] failed to inspect image: failed to get image config: failed to parse config: invalid character '}' looking for beginning of object key string
解决方案：
- 验证镜像完整性：
nerdctl image verify <image_id> - 清理损坏镜像：
nerdctl rmi --force <image_id> - 使用校验和拉取：
nerdctl pull example.com/image@sha256:xxxx
四、Rootless模式特有错误（4xx系列）
4.1 Cgroup配置错误（错误码401）
典型错误：
FATA[0000] failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: unable to apply cgroup configuration: Permission denied
解决方案：
# 安装用户会话DBus
sudo apt-get install -y dbus-user-session
# 启动用户DBus服务
systemctl --user start dbus
# 验证cgroup版本
stat -fc %T /sys/fs/cgroup/
4.2 端口转发驱动问题（错误码402）
症状：端口映射成功但无法从外部访问，无错误日志
根本原因：Rootless模式默认使用rootlesskit端口驱动，不支持源IP透传
解决方法：
# 临时切换为slirp4netns驱动
nerdctl run -p 8080:80 --port-driver=slirp4netns nginx
# 永久配置（/etc/nerdctl/nerdctl.toml）
port_driver = "slirp4netns"
五、构建相关错误（5xx系列）
5.1 Buildkit连接错误（错误码500）
错误信息：
FATA[0000] buildx failed with: error during connect: could not connect to buildkit daemon: failed to dial gRPC: dial unix /run/buildkit/buildkitd.sock: connect: no such file or directory
修复步骤：
- 启动buildkit服务：
systemctl start buildkit - 验证服务状态：
systemctl status buildkit - 检查socket文件：
ls -la /run/buildkit/buildkitd.sock
5.2 构建缓存清理（错误码501）
解决方案：
# 清理构建缓存
nerdctl builder prune --all --force
# 查看缓存使用情况
du -sh ~/.local/share/buildkit/
六、错误码速查表
| 错误码范围 | 错误类型 | 典型场景 | 解决方案摘要 |
|---|---|---|---|
| 111 | 连接错误 | containerd未启动 | systemctl start containerd |
| 125 | 命名空间错误 | 访问k8s容器 | --namespace=k8s.io |
| 200 | 端口冲突 | 绑定已占用端口 | 更换端口或终止占用进程 |
| 255 | 状态冲突 | 停止已停止容器 | 检查容器状态：nerdctl ps -a |
| 301 | 仓库不可达 | DNS解析失败 | 检查网络/仓库URL |
| 310 | 镜像损坏 | 配置解析错误 | 强制删除损坏镜像 |
| 401 | Cgroup权限 | Rootless模式权限不足 | 启动dbus-user-session |
| 402 | 端口转发 | 外部无法访问容器端口 | 切换为slirp4netns驱动 |
| 500 | Buildkit错误 | 构建服务未启动 | systemctl start buildkit |
七、高级诊断工具
7.1 内置调试选项
# 启用详细日志
nerdctl --debug run nginx
# 查看API请求
NERDCTL_DEBUG=1 nerdctl ps
7.2 错误日志位置
| 组件 | 日志路径 | 关键信息 |
|---|---|---|
| containerd | /var/log/containerd.log | 服务启动、镜像拉取 |
| nerdctl | ~/.local/share/nerdctl/nerdctl.log | 命令执行、用户操作 |
| buildkit | /var/log/buildkitd.log | 构建过程、缓存管理 |
7.3 系统状态检查脚本
#!/bin/bash
# nerdctl诊断脚本
echo "=== 系统信息 ==="
uname -a
echo -e "\n=== containerd状态 ==="
systemctl status containerd --no-pager
echo -e "\n=== 命名空间列表 ==="
nerdctl namespace ls
echo -e "\n=== 网络检查 ==="
nerdctl network ls
echo -e "\n=== 存储状态 ==="
nerdctl info | grep -A 10 "Storage Driver"
八、总结与最佳实践
-
错误预防：
- 定期清理无用资源：
nerdctl system prune -a - 使用固定版本镜像而非
:latest - 监控磁盘空间：
df -h /var/lib/containerd
- 定期清理无用资源：
-
故障恢复：
- 备份关键镜像：
nerdctl save -o backup.tar <image> - 配置持久化：定期备份
/etc/containerd/config.toml - 建立回滚点：使用
nerdctl commit保存容器状态
- 备份关键镜像：
-
社区支持：
- GitHub Issues：https://github.com/containerd/nerdctl/issues
- Slack频道：#containerd-nerdctl（CNCF Slack）
- 每周社区会议：太平洋时间周四10:00
通过本手册提供的错误码解析和解决方案，您可以快速定位并解决nerdctl日常使用中90%以上的常见问题。对于复杂场景，建议结合源码调试和社区支持进一步排查。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
