> ## Documentation Index
> Fetch the complete documentation index at: https://vibex.peatboy.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤碼

> Vibex 返回的結構化錯誤碼及其處理方式。

Vibex 的失敗以**結構化錯誤碼**返回，介面會顯示為 `錯誤碼: 說明`。提交 Issue 時請附上完整的錯誤碼字串——它比日誌正文更有用。

## 遠端與配對

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `remote_pairing_code_invalid` | 配對碼錯誤、已被使用或不存在。 | 在權威端重新生成。 |
| `remote_pairing_code_expired` | 配對碼已過期（預設 5 分鐘，最長 30 分鐘）。 | 重新生成並儘快使用。 |
| `remote_pairing_link_invalid` | 連線串格式錯誤，或其中地址不是允許的區域網地址。 | 使用權威端列印的完整連線串。 |
| `device_revoked` | 裝置已被撤銷。 | 重新配對。 |
| `resync_required` | 檢測到序號或游標缺口。 | 等待權威端重新同步。 |
| `server_shutdown` | 權威執行階段正在關閉。 | 重啟後重連。 |
| `permission_denied` | 當前裝置權限級別不足。 | 用更高權限級別重新配對。 |

## 會話與工作區

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `remote_agent_workspace_root_missing` | 會話請求的工作區目錄在權威端不存在。 | 確認目錄已掛載且位於 `VIBEX_WORKSPACE_ROOTS` 內。 |
| `remote_agent_workspace_mode_mismatch` | 請求的工作區模式與權威端記錄不一致。 | 在權威端重新選擇工作區。 |

## 檔案與內容

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `file_external_revision_changed` | 儲存時檔案已被外部程序修改。 | 重新載入後再決定如何合併。 |
| `office_legacy_format_unsupported` | `doc` / `xls` / `ppt` 無法渲染。 | 用系統預設應用開啟，或轉換為新格式。 |

## 配置與匯入

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `provider_native_import_source_missing` | 找不到要匯入的原生配置來源。 | 確認對應 Agent 的配置檔案存在。 |

## 用量統計

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `agent_usage_query_too_large` | 查詢超過 100000 行上限。 | 縮小時間範圍或增加篩選條件。 |

## 釋出與更新

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `release_channel_override_rejected` | 試圖在執行階段切換髮布通道。 | 安裝對應通道的版本。 |
| `stable_channel_requires_release_build` | Stable 通道需要正式釋出構建。 | 使用正式釋出的安裝包。 |

## SSH 與 WSL

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `ssh_client_missing` / `ssh_spawn_failed` | 桌面端沒有可用的 SSH 客戶端。 | 安裝 OpenSSH；Windows 使用 WSL。 |
| `ssh_host_key_unknown` | 主機金鑰不在 `known_hosts` 中。 | 先在終端機連線並核對指紋。 |
| `ssh_host_key_changed` | 主機金鑰與記錄不一致。 | 與主機所有者核對後再決定是否更新 `known_hosts`。 |
| `ssh_auth_failed` | 非互動認證失敗。 | 檢查 Key、ssh-agent 和 IdentityFile。 |
| `ssh_connection_refused` | 目標沒有 SSH 服務。 | 安裝/啟動 sshd，或用 bootstrap。 |
| `ssh_environment_glibc_too_old` / `ssh_environment_missing_glibc` | 遠端 glibc 低於 2.35 或缺失。 | 換受支援的發行版；musl 主機不支援。 |
| `ssh_environment_disk_low` | 遠端 home 空間不足。 | 至少釋放 512 MiB。 |
| `ssh_environment_port_busy` | 執行階段埠被佔用。 | 釋放埠或重試。 |
| `ssh_runtime_start_failed` / `ssh_runtime_health_timeout` | 執行階段沒有啟動或健康檢查超時。 | 檢視遠端 `server.log`，修復後重試。 |
| `ssh_tunnel_*` | 隧道建立、保持或停止失敗。 | 檢查本地埠和 SSH 連線，重試。 |
| `ssh_upgrade_incompatible` | 執行階段與桌面端版本不相容。 | 按相容性狀態更新執行階段或 Vibex。 |

## 瀏覽器

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `browser_missing` | 找不到 Chrome、Chromium 或 Edge。 | 安裝受支援的瀏覽器。 |
| `browser_unavailable` | 瀏覽器服務不可用或正在關閉。 | 重新打開面板；檢查執行階段日誌。 |
| `browser_ref_stale` | 元素引用已過期。 | 重新觀察頁面後再操作。 |
| `browser_element_not_found` / `browser_element_not_visible` | 目標元素不存在或不可見。 | 重新觀察；必要時滾動或等待。 |
| `browser_navigation_denied` / `browser_navigation_approval_required` | 導航被拒絕或需要批准。 | 在面板裡確認；不要繞過核准。 |
| `browser_wait_timeout` | 等待條件超時。 | 檢查選擇器或頁面狀態。 |
| `browser_feature_disabled` | 當前執行階段或平台關閉了瀏覽器面板。 | 檢查設定和平台支援。 |

## 電腦操作

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `computer_feature_disabled` | 總開關關閉。 | 在 **設定 → 電腦操作** 開啟。 |
| `computer_engine_missing` / `computer_driver_daemon_missing` | 驅動或 helper 未安裝/未執行。 | 安裝驅動並重新檢測。 |
| `computer_accessibility_bridge_missing` | Linux 上輔助功能匯流排不可用。 | 安裝/啟動 AT-SPI；X11 下仍可能降級。 |
| `computer_credential_target_blocked` | 目標是密碼管理器或安全輸入框。 | 硬拒絕，不能批准。 |
| `computer_element_reference_stale` | 元素引用已過期。 | 重新觀察應用。 |
| `computer_stopped_by_user` | 你按下了應急停止。 | 手動重新開啟後才能繼續。 |
| `computer_paused_offline` | 客戶端斷線，操作已暫停。 | 重新連線並確認恢復。 |

## 供應商與閘道器

| 錯誤碼 | 含義 | 處理 |
| - | - | - |
| `provider_authentication_required` | 供應商或 Agent 需要認證。 | 登入 Agent 或補充 Provider Key。 |
| `provider_profile_not_found` | 配置不存在或已刪除。 | 重新整理配置中心，重新選擇。 |
| `agent_model_interface_unsupported` | 當前 Agent 不支援所選介面協議。 | 換協議或換 Agent。 |
| `model_gateway_port_invalid` | 閘道器埠低於 1024 或不可用。 | 換一個高於 1023 的空閒埠。 |
| `model_gateway_cooldown_invalid` | 冷卻時間不在 1 毫秒到 1 天之間。 | 調整冷卻設定。 |
| `model_gateway_token_limit_invalid` | Token 上限無效。 | 輸入正整數或留空。 |
| `reasoning_effort_unavailable` | 所選思考檔位不被模型支援。 | 換檔位或留空。 |

## 狀態值

這些不是錯誤，但經常被誤讀：

| 值 | 出現在 | 含義 |
| - | - | - |
| `stale` | 終端機、執行狀態 | 上次觀察到的狀態已失效，不代表程序仍存活。 |
| `revoked` | 裝置 | 授權已被撤銷。 |
| `running` | 會話 | **只是上次觀察到的狀態**，重啟後需要重新探測。 |
| `Not reported` / `Partial` | 用量上報覆蓋 | 資料缺失或不全，**不要當作零**。 |

## 通用排查順序

1. 確認權威執行階段正在執行，以及當前連的是哪一個（本地內嵌，還是遠端伺服器）。
2. 確認當前專案和工作區正確——`Local` 和 `Worktree` 是不同目錄。
3. 確認裝置權限級別足夠（寫操作需要 `full_control`）。
4. 檢視時間線最近一條事件，確認是否在等待你處理核准或詢問表單。
5. 仍無法解決時，按[故障排查](https://vibex.peatboy.com/docs/zh-TW/troubleshooting.md)提交脫敏資訊。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.