> ## Documentation Index > Fetch the complete documentation index at: https://extension.js.org/llms.txt > Use this file to discover all available pages before exploring further. # 錯誤碼 > Extension.js schema-1 信封所使用、長期穩定的 E_* 錯誤碼表，依領域分組，並附上 codes.json 中的折疊名稱與舊名稱對應。 請依穩定的錯誤碼做分支判斷，絕不要依訊息文字。 每一個失敗信封都會帶上同一張表中的某個 `E_*` 錯誤碼。錯誤碼只會新增，絕不會被改名或移除。錯誤碼旁邊的訊息屬於自由文案，任何版本都可能更動。 這張表隨 `extension-develop/contract/codes.json` 一起發布，參見 [結果信封](/docs/contracts/result-envelope)。 ## 用法 | 錯誤碼 | 意義 | | ---------------------------------- | ---------------------------------------- | | `E_ARGS` | 缺少必要引數，或呼叫方式格式錯誤。 | | `E_INVALID_OPTION` | 某個旗標或引數的值不在允許的集合內。 | | `E_FLAG_VALUE_INVALID` | 某個旗標的值未通過驗證。 | | `E_FLAG_NOT_SUPPORTED_HERE` | 該旗標存在，但不適用於這個指令或這個目標。 | | `E_REMOVED_FLAG` | 該旗標已從 CLI 移除。 | | `E_UNKNOWN_COMMAND` | 沒有子指令符合這個名稱。 | | `E_NODE_VERSION` | 執行中的 Node 版本低於支援的最低版本。 | | `E_COMMAND_UNSUPPORTED_FOR_TARGET` | 該指令不支援所要求的瀏覽器目標。 | | `E_UNSUPPORTED_BROWSER` | 所要求的廠商不在支援的瀏覽器清單內。 | | `E_BROWSER_NOT_INSTALLABLE` | 該瀏覽器隨作業系統提供，CLI 無法安裝它。 | | `E_PARENT_GONE` | `--parent-pid` 指定的宿主處理程序已死亡，開發伺服器因而自行結束。 | | `E_REMOTE_URL_UNSUPPORTED` | 該操作不接受遠端 URL。 | ## 專案 | 錯誤碼 | 意義 | | ---------------------------- | ------------------------------------------------------- | | `E_PROJECT_NOT_FOUND` | 解析出的專案資料夾不存在。 | | `E_CONFIG_LOAD` | `extension.config.js` 在載入時拋出例外。 | | `E_MANAGED_DEP_CONFLICT` | 專案宣告了一個由工具鏈託管的套件。 | | `E_DEPENDENCY_INSTALL` | 安裝專案相依套件失敗。 | | `E_TYPES_EMIT` | 寫出 `extension-env.d.ts` 失敗。 | | `E_TSCONFIG_MISSING` | 存在 TypeScript 原始碼，但 `package.json` 旁沒有 `tsconfig.json`。 | | `E_OPTIONAL_DEP_UNRESOLVED` | 某個選用相依契約無法解析。 | | `E_OPTIONAL_DEP_LOAD` | 某個選用相依已解析，但載入失敗。 | | `E_OPTIONAL_DEP_UNKNOWN` | 未知的選用相依契約 id。 | | `E_COMPANION_EXTENSION_PATH` | 某個搭配擴充功能路徑逸出了 `extensions/`，或未產出任何未封裝內容。 | | `E_MANIFEST_IN_PUBLIC` | `manifest.json` 被放在 `public/` 底下。 | | `E_RUNTIME_NOT_FOUND` | extension-develop 執行階段遺失或未編譯。 | ## Manifest | 錯誤碼 | 意義 | | -------------------------------- | ----------------------------------------------- | | `E_MANIFEST_NOT_FOUND` | 解析出的根目錄下沒有 `manifest.json`。 | | `E_MANIFEST_INVALID` | manifest 不是可解析的 JSON，或不是 WebExtension manifest。 | | `E_MANIFEST_SHAPE` | 某個 manifest 欄位的結構不正確。 | | `E_MANIFEST_PAGE_MISSING` | manifest 參照的某個 HTML 頁面不存在。 | | `E_MANIFEST_VERSION_UNSUPPORTED` | 這個目標不支援該 `manifest_version`。 | | `E_MANIFEST_LOAD_BLOCKERS` | manifest 中含有瀏覽器在載入時會拒絕的欄位。 | | `E_MANIFEST_PERMISSION_MISSING` | manifest 中缺少某個必要的權限。 | | `E_MANIFEST_MSG_KEY_MISSING` | 預設語系中缺少某個 `__MSG_x__` 鍵。 | | `E_MANIFEST_EMIT` | manifest 的產出或寫入失敗。 | | `E_RESTART_REQUIRED` | 某個進入點欄位變更，開發伺服器必須重新啟動。 | ## 編譯 | 錯誤碼 | 意義 | | ---------------------------- | ---------------------------------------- | | `E_FIRST_COMPILE` | 工作階段的第一次編譯失敗，因此什麼都沒有載入。 | | `E_COMPILE` | 編譯結束時帶有錯誤。 | | `E_COMPILE_FATAL` | 編譯器本身失敗，或回傳了無法使用的統計資料。 | | `E_MODULE_NOT_FOUND` | 某個模組識別字無法解析。 | | `E_ENTRY_NOT_FOUND` | 某個 manifest、HTML 或 JSON 進入點指向不存在的檔案。 | | `E_ASSET_MISSING` | 缺少某個圖示、靜態資源或 JSON 相依。 | | `E_SCRIPT_DEP_MISSING` | 某個執行階段指令稿相依無法被追蹤到。 | | `E_RESERVED_FOLDER` | 違反了保留的 `scripts/` 資料夾結構。 | | `E_CSS_PARSE` | 某個樣式表解析失敗。 | | `E_CSS_PREPROCESSOR_MISSING` | 要求了某個 CSS 前處理器，但無法解析到它。 | | `E_CSS_DEAD_REF` | CSS 中的某個 `url()` 指向不存在的內容。 | | `E_INTEGRATION_INSTALL` | 某個框架整合安裝失敗。 | | `E_POLYFILL_NOT_FOUND` | 要求了 webextension-polyfill，但它並不存在。 | | `E_LOCALES_LAYOUT` | `_locales` 的結構或 `messages.json` 不合法。 | | `E_WAR_INVALID` | `web_accessible_resources` 的結構或比對樣式遭到拒絕。 | | `E_MATCH_PATTERN_INVALID` | 瀏覽器拒絕了某個 content script 的比對樣式。 | | `E_BACKGROUND_REQUIRED` | 重新載入執行階段需要一個 background chunk，但它並不存在。 | | `E_CONTENT_SCRIPT_SYNTAX` | 某個 content script 解析失敗。 | | `E_NO_ENTRYPOINTS` | 這次編譯產出了零個進入點。 | | `E_REMOTE_RESOURCE_BLOCKED` | 某個遠端指令稿或樣式表被擴充功能 CSP 封鎖。 | | `E_PERF_BUDGET` | 某個資源超出了它的大小預算。 | | `E_ZIP_SKIPPED` | 打包因某個已說明的原因被略過。 | | `E_ENV_NO_MATCH` | 沒有任何 `.env` 檔案符合目前模式。 | ## 遠端專案與網路 | 錯誤碼 | 意義 | | -------------------------- | ------------------------ | | `E_REMOTE_FETCH_TIMEOUT` | 某次遠端擷取超過了它的逾時時間。 | | `E_REMOTE_DOWNLOAD` | 遠端擴充功能的下載或解壓縮失敗。 | | `E_REMOTE_ZIP_INVALID` | 該遠端 URL 回傳的並不是 zip。 | | `E_LOCAL_ZIP_NOT_FOUND` | 被參照的本機 zip 遺失，或根本不是 zip。 | | `E_PROJECT_DOWNLOAD_EMPTY` | 下載成功，但解壓出的資料夾並不存在。 | | `E_NETWORK` | 某個網路請求失敗或逾時。 | ## 瀏覽器執行檔與啟動 | 錯誤碼 | 意義 | | --------------------------------- | -------------------------- | | `E_BROWSER_NOT_FOUND` | 所要求的廠商沒有已安裝的執行檔。 | | `E_BROWSER_BINARY_REQUIRED` | `-based` 目標需要明確的執行檔路徑。 | | `E_BROWSER_BINARY_INVALID` | 給定的執行檔路徑不存在，或無法執行。 | | `E_BROWSER_LAUNCH` | 瀏覽器處理程序無法產生，或在啟動時就死掉了。 | | `E_BROWSER_EXITED` | 已啟動的瀏覽器結束了，而伺服器仍在執行。 | | `E_BROWSER_START_TIMEOUT` | 瀏覽器始終沒有送出啟動訊號。 | | `E_PROFILE_LOCKED` | 該設定檔目錄被另一個瀏覽器處理程序占用。 | | `E_LAUNCH_SKIPPED_COMPILE_ERRORS` | 因為編譯失敗，所以沒有啟動瀏覽器。 | | `E_INSTANCE_AMBIGUOUS` | 有多個存活的實例符合所要求的 id。 | | `E_WSL_INTEROP` | WSL 互通無法解析到 Windows 上的瀏覽器。 | | `E_BROWSER_DOWNLOAD` | 下載或安裝瀏覽器失敗。 | | `E_BROWSER_INSTALL_PRIVILEGE` | 這次安裝需要一個互動式的特權工作階段。 | | `E_BROWSER_UNINSTALL` | 移除已安裝的瀏覽器失敗。 | | `E_UNINSTALL_NOOP` | 沒有可以移除的東西。 | ## 瀏覽器執行階段 | 錯誤碼 | 意義 | | -------------------------- | ----------------- | | `E_EXTENSION_LOAD_REFUSED` | 瀏覽器拒絕了這個未封裝的擴充功能。 | | `E_ADDON_INSTALL` | Gecko 暫時附加元件安裝失敗。 | ## 除錯協定 | 錯誤碼 | 意義 | | ----------------------------- | ------------------------ | | `E_BROWSER_CONNECT` | 無法開啟除錯連線。 | | `E_BROWSER_CONNECTION_CLOSED` | 除錯 socket 在工作階段中途關閉。 | | `E_CDP_NOT_CONNECTED` | 在沒有存活 CDP 傳輸的情況下發出了某個操作。 | | `E_CDP_TIMEOUT` | 某個 CDP 指令或 load 事件逾時。 | | `E_CDP_OP_FAILED` | 透過 CDP 執行的某個擴充功能操作失敗。 | | `E_EXTENSION_ID_UNKNOWN` | 無法透過 CDP 判定擴充功能 id。 | | `E_RDP_PROTOCOL` | 出現格式錯誤或非預期的 RDP 交換。 | ## 開發伺服器 | 錯誤碼 | 意義 | | ---------------------- | --------------------- | | `E_DEV_SERVER_START` | 開發伺服器啟動失敗。 | | `E_DEV_SERVER_TIMEOUT` | 開發伺服器啟動超過了它的逾時時間。 | | `E_PORT_IN_USE` | 所要求的埠號已被占用，已自動改用其他埠號。 | | `E_PORT_UNAVAILABLE` | 在所要求的埠號附近找不到可綁定的空閒埠號。 | ## 就緒契約 | 錯誤碼 | 意義 | | ---------------------- | ----------------------- | | `E_SESSION_NOT_FOUND` | 這個專案與瀏覽器沒有存活的工作階段契約。 | | `E_SESSION_EXISTS` | 這個專案與瀏覽器已經存在一個存活的工作階段。 | | `E_SESSION_STOPPED` | 工作階段契約回報該工作階段已停止。 | | `E_READY_TIMEOUT` | 工作階段尚未就緒，`--wait` 就已逾時。 | | `E_READY_ERROR_STATUS` | 就緒契約回報該工作階段處於錯誤狀態。 | ## 控制通道 | 錯誤碼 | 意義 | | -------------------------- | ---------------------------- | | `E_CONTROL_UNAVAILABLE` | 控制通道不存在、不相符，或沒有回應。 | | `E_CONTROL_DENIED` | 工作階段拒絕了這次控制操作。 | | `E_TOKEN_MISSING` | 該操作需要一個工作階段權杖，但它並不存在。 | | `E_EVAL_REFUSED` | 該工作階段停用了 eval，或權杖不相符。 | | `E_TIMEOUT` | 該操作在逾時時間內沒有回應。 | | `E_NOT_IMPLEMENTED` | 該操作在這個情境或這個引擎上尚未實作。 | | `E_TARGET_NOT_FOUND` | 沒有任何分頁、frame 或情境符合所要求的目標。 | | `E_HEADED_WINDOW_REQUIRED` | 該介面需要一個有頭的瀏覽器視窗，而這個工作階段沒有。 | | `E_USER_GESTURE_REQUIRED` | 該介面需要一次真實的使用者手勢，而呼叫端無法合成它。 | | `E_EVAL` | 被求值的運算式在頁面內拋出例外。 | | `E_INSPECT` | 在受檢端內部進行 DOM 檢查失敗。 | | `E_STORAGE` | `chrome.storage` 拒絕了這次讀取或寫入。 | ## 日誌 | 錯誤碼 | 意義 | | ------------------- | ---------------- | | `E_LOGS_NOT_FOUND` | 這個專案與瀏覽器沒有日誌串流。 | | `E_LOGS_STREAM_GAP` | follow 串流掉了部分事件。 | ## 建立 | 錯誤碼 | 意義 | | ---------------------------- | -------------------------- | | `E_TEMPLATE_NOT_FOUND` | 該範本不在目錄清單中，或沒有 manifest。 | | `E_DESTINATION_NOT_EMPTY` | 目的地已經有會衝突的檔案。 | | `E_DESTINATION_NOT_WRITABLE` | 目的地目錄無法寫入。 | | `E_CREATE_DIR` | 無法建立目標目錄。 | | `E_CREATE_WRITE` | 某個 scaffold 檔案無法寫入。 | | `E_CREATE_TESTS_SETUP` | 內建測試設定失敗。 | | `E_GIT_SKIPPED` | 因為沒有 git，所以略過了 `git init`。 | ## 其他所有情況 | 錯誤碼 | 領域 | 意義 | | ------------------------ | --------- | ---------------------- | | `E_PREVIEW_NO_DIST` | preview | 解析出的輸出路徑下沒有未封裝的擴充功能。 | | `E_SAFARI_TOOLCHAIN` | safari | Safari 工具鏈不可用，或某次呼叫失敗。 | | `E_PUBLISH_REJECTED` | publish | 平台拒絕了這次上傳。 | | `E_AUTH_REQUIRED` | publish | 該操作需要一個驗證權杖，但它並不存在。 | | `E_TELEMETRY_WRITE` | telemetry | 無法寫入遙測同意檔案。 | | `E_DOCTOR_CHECKS_FAILED` | doctor | 有一項或多項 doctor 檢查回報失敗。 | | `E_INTERRUPTED` | internal | 該操作在完成之前被中斷。 | | `E_INTERNAL` | internal | 一個非預期的錯誤傳到了最上層的錯誤匯集點。 | ## 折疊名稱與舊名稱 `codes.json` 在這張表之外還帶了兩份額外對應： * `folded` 把較細的清單名稱對應到已發布的家族錯誤碼上。例如 `E_ARG_REQUIRED` 會折疊為 `E_ARGS`，`E_BROWSER_NOT_INSTALLED` 會折疊為 `E_BROWSER_NOT_FOUND`。 * `legacy` 把信封出現之前的三種命名慣例對應到這張表上：`ready.json` 的 snake\_case 錯誤碼（`profile_locked` 對應 `E_PROFILE_LOCKED`）、PascalCase 的錯誤名稱（`TargetNotFound` 對應 `E_TARGET_NOT_FOUND`），以及 kebab-case 的 doctor 檢查項 id（`eval-token` 對應 `E_TOKEN_MISSING`）。 如果你的取用端遇到表中沒有的名稱，請先透過這些對應解析出來，再做分支判斷。 ## 下一步 * 在 [結果信封](/docs/contracts/result-envelope) 中了解錯誤碼會流經哪些地方。 * 在 [生命週期串流](/docs/contracts/lifecycle-stream) 中即時觀察失敗訊框。