BrowserSkill错误码速查手册：cdp_failed、timeout、cancelled常见错误一次看懂

BrowserSkill错误码速查手册cdp_failed、timeout、cancelled常见错误一次看懂【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkillBrowserSkill 是一款让 AI Agent 直接操作你真实、已登录浏览器的浏览器自动化工具bsk命令行 浏览器扩展协同工作驱动 Chrome/Edge 完成点击、填表、截图、长截图等任务。当自动化失败时终端会抛出一个结构化错误码。本手册带你一次看懂cdp_failed、timeout、cancelled等全部 13 个错误码的含义、退出码分类与修复方法遇到报错不再摸不着头脑。 30秒看懂BrowserSkill错误码体系怎么设计的BrowserSkill 的报错不是一锅粥而是三件套错误码code13 个稳定枚举值如cdp_failed、timeout定义在 crates/bsk-protocol/src/error.rs退出码exit code0~5 五档方便脚本判断谁的锅修复提示hint每个错误码都内置一句可操作的修复建议。退出码分档规则设计文档 §3.1一目了然退出码含义一句话理解0成功一切正常1用户错误参数写错、资源不存在、沙箱拒绝——是你的命令问题2协议/传输错误连不上守护进程、命令被取消——是通道问题3浏览器/CDP 失败浏览器拒绝了底层调用——是浏览器的问题4超时操作等太久了——是时间问题5版本不兼容CLI 与扩展版本不匹配——是版本问题这张错误码 → 退出码 → 提示语的对照表由 crates/bsk-cli/src/cli/render_error.rs 统一维护并配有单元测试锁定映射关系render_error.rs 测试所以你可以放心地依赖它。 13 个错误码总表一张表全记住错误码退出码含义快速修复invalid_params1命令参数不合法运行bsk cmd --help检查格式not_found1请求的资源会话/标签页/浏览器不存在bsk session list/bsk browsers看当前状态permission_denied1Agent Window 沙箱拒绝操作先用bsk tab borrow tab-id --session id借入标签页unsupported1当前构建不支持该操作用bsk --version与更新日志确认功能是否可用no_browser_connected1守护进程没有已连接的浏览器打开扩展弹窗等状态显示已连接multiple_browsers_online1有多个浏览器同时在线用--browser id-or-label指定目标protocol_error2与守护进程通信的协议出错在bsk status中核对 protocol versioncancelled2操作被取消Ctrl-C 或远程 cancel确认中断来源按需重跑user_aborted2用户主动打断如点击停止按钮若非误操作重新运行即可cdp_failed3浏览器拒绝了底层 CDP 调用确认标签页仍处于已加载状态重试重载标签页可重置卡住的 DevTools 会话timeout4操作超时重试若持续超时查bsk logs并确认浏览器仍在响应unknown_method5守护进程不认识该 RPC 方法同时升级bskCLI 与浏览器扩展version_too_old5对端版本过旧无法通信两边都升级满足最小兼容协议版本 cdp_failed浏览器拒绝了你的请求退出码 3这是自动化场景里最经典的报错。它的通用含义是browser rejected the underlying CDP call浏览器拒绝了底层 Chrome DevTools Protocol 调用官方提示hint: confirm the tab is still in a loaded state and retry; reloading the tab usually resets a stuck DevTools session 确认标签页仍处于已加载状态并重试重载标签页通常能重置卡住的 DevTools 会话真正的病因藏在data.reason字段里常见子场景reason含义该怎么办screenshot_capture_failed可见标签页截图与 CDP 合成器兜底双双失败属浏览器端渲染问题重载标签页、重启浏览器或调整 Chrome 版本screenshot_page_hidden截图过程中页面变为隐藏截图前保持目标标签页可见screenshot_navigation截图过程中页面发生了导航先检查当前页面再重新开始截图screenshot_stale_frame滚动后截图像素未更新保持截图窗口可见不要重复拼接旧视口图cdp_extension_access_deniedChrome 阻止了对其他扩展内容的 CDP 访问禁用冲突扩展并重载或bsk navigate url离开该页面fill_target_changed/fill_focus_lost填表时目标变了 / 页面把焦点抢走了先重新观察页面处理弹窗或重渲染再重试fill_failed/fill_value_mismatch填表遇到浏览器或页面脚本错误 / 结果无法确认先观察字段现状再决定是否重试不要盲目重复 fillinput_not_ready浏览器未就绪输入实际未发出输入没有生效重新观察页面后可直接重试input_outcome_unknown输入可能已经生效不要重复输入先观察页面结果⏱️ timeout操作超时了退出码 4通用提示是重试命令如果超时持续出现用bsk logs排查并确认浏览器仍在响应。但timeout也有子病因reason含义该怎么办session_busy上一条会话命令还在跑等它跑完、Ctrl-C 取消它或重启会话screenshot_watchdog_timeout长截图过程中与页面失去联系加大总时限救不了页面通信问题先确认浏览器有响应screenshot_loading_stalled页面加载在底部卡住若当前已加载范围满足需求可用--full-page --scope currenttransfer_timeout文件传输在浏览器分发后超时effect_state为 unknown/committed 时不要重试先检查页面cancel_cleanup_timeout取消操作未在时限内完成原操作可能已生效先观察页面再决定要不要重试file_input_probe_failed上传事务未能建立不要盲目重试同一上传可用bsk request-help求助人工 cancelled 与 user_aborted取消不是失败退出码 2cancelled的提示是the previous command was interrupted (Ctrl-C or a remotecancelrequest)——上一条命令被 Ctrl-C 或远程cancel请求打断了。它代表流程被中断不代表执行出错退出码为 2。与它容易混淆的两个近亲user_aborted退出码 2用户在界面上主动请求了打断比如点了 Agent Window 的停止按钮提示会写明若非误操作可重跑screenshot_user_cancelledcancelled的一个 reason整页截图被用户输入取消官方明确提示respect the interruption; do not automatically retry——尊重中断不要自动重试。⚠️关键原则——看effect_state再决定重试。错误载荷里的data.effect_state字段有三个值none动作完全没生效可以安全重试unknown不确定是否已生效禁止盲目重试先观察页面committed动作已生效直接检查结果即可。这也是官方提示中反复出现 do not repeat the input / do not retry 的原因——对自动化来说重复执行比失败更危险。 其他高频错误码连接类问题排查no_browser_connected退出码 1守护进程找不到任何已连接浏览器。修复方法写在提示里——打开浏览器里的 BrowserSkill 扩展等弹窗显示已连接READYmultiple_browsers_online退出码 1多个浏览器同时在线CLI 不知道听谁的。用--browser instance_id-or-label指定目标或先跑bsk browsers列出在线浏览器。invalid_params/not_found/permission_denied退出码 1这一档都是用户输入问题常见 reasonref_not_found观察引用ref失效 → 对当前标签页重跑bsk observe使用新引用selector_not_foundCSS 选择器没匹配到元素 → 核对选择器或等元素出现element_not_visible目标元素没有可见几何 → 重跑 snapshot 选一个可见的子元素或等待/滚动/重载后再试borrow_conflict标签页正被另一个会话借用 → 让借出方bsk tab return tab-id --session id归还target_not_fillable/target_not_select目标不是可填输入框 / 不是select→ 观察页面后改用正确的操作指令。protocol_error/unknown_method/version_too_old退出码 2/5都是版本漂移症状——CLI、守护进程、扩展三者版本不齐。unknown_method是典型的方法形状不匹配把bskCLI 与浏览器扩展一起升级、并用bsk daemon restart重启守护进程即可。️ 怎么读终端里的报错error / hint / details 三行结构人类可读模式下每条错误固定输出三段渲染逻辑见 crates/bsk-cli/src/cli/error.rserror: target element has no visible geometry hint: rerun snapshot and choose a visible child ref, or wait/scroll/reload before retrying details: element not visible (no content quads)error:友好的一行总结来自上面那张对照表hint:可执行的修复建议details:守护进程的原始细节给需要深挖上下文的人看。如果你没看到error:而是收到类似 daemon unreachable 的传输层报错退出码 2提示会直接告诉你is the daemon running? trybsk daemon startorbsk status——守护进程没起来这是最容易被忽视的第一步。脚本场景请加--json输出为扁平结构方便jq处理{ code: multiple_browsers_online, message: more than one browser, hint: use --browser instance_id-or-label to target a specific browser (run bsk browsers to list online browsers), exit_code: 1, data: { browsers: [{ instance_id: alpha }] } }code、exit_code、data.reason就是你在本文速查表中检索的三个抓手。 排错三步法status → doctor → logs遇到报错按这个顺序排查能解决 90% 的问题bsk status # 第一步守护进程在不在浏览器连上没协议版本对不对 bsk doctor # 第二步引导式体检逐项检查并给出修复建议 bsk logs # 第三步看最近 200 行守护进程日志定位卡在哪对应源码status.rs、doctor.rs、logs.rs。 相关源码与文档索引错误码定义crates/bsk-protocol/src/error.rs错误码 → 提示语/退出码对照表crates/bsk-cli/src/cli/render_error.rs细粒度 reason 常量crates/bsk-cli/src/cli/render_error.rsCLI 错误渲染入口crates/bsk-cli/src/cli/error.rsbsk 命令文档crates/bsk-cli/README.md架构说明docs/architecture.md长截图行为说明含取消与导出docs/long-screenshot.md 小结先看退出码定档1 查参数、2 查连接与取消、3 查浏览器、4 查超时、5 查版本再看data.reason定位子场景对照上表的修复建议操作effect_state为unknown时绝不盲目重试先bsk observe观察页面现状卡住了就bsk status→bsk doctor→bsk logs三步排查。掌握这套速查手册BrowserSkill 的报错就从天书变成了导航图——照提示操作多数问题一次就能解决。【免费下载链接】BrowserSkillLet AI agents use your real, logged-in browser without interrupting your work. CLI extension for browser automation across any shell-capable AI agent.项目地址: https://gitcode.com/GitHub_Trending/br/BrowserSkill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考