What causes "当前 API 服务地址不可用" in jlcodes99/cockpit-tools?

Create/enable a local API service collection first so `localAccessCollection` is populated, then activate.

codex.localAccess.testUnavailable

codex.localAccess.testUnavailable

Error message

当前 API 服务地址不可用

What it means

Thrown by `handleActivateLocalAccess` when `localAccessCollection` is null/undefined — there is no local API service collection (address) available to activate, so the "test/activate" target is unavailable (code `codex.localAccess.testUnavailable`, message "当前 API 服务地址不可用").

Source

Thrown at src/pages/useCodexAccountsLocalAccessController.tsx:1738

            ? t("codex.localAccess.enabledSuccess", "API 服务已启用")
            : t("codex.localAccess.disabledSuccess", "API 服务已停用"),
        });
        return nextState;
      } catch (error) {
        console.error("Failed to toggle local access service:", error);
        throw new Error(String(error).replace(/^Error:\s*/, ""));
      } finally {
        setLocalAccessSaving(false);
      }
    }, [localAccessCollection, requestLocalAccessRiskNotice, setMessage, t]);
  
    const handleActivateLocalAccess = useCallback(
      async (options?: {
        showSuccessMessage?: boolean;
        instanceId?: string | null;
      }) => {
        if (!localAccessCollection) {
          throw new Error(
            t("codex.localAccess.testUnavailable", "当前 API 服务地址不可用"),
          );
        }
        if (!localAccessCollection.enabled) {
          const confirmedEnableAndSwitch = await confirmDialog(
            t(
              "codex.localAccess.enableBeforeActivateMessage",
              "API 服务当前未启用，需要先启用服务。是否启用并切号？",
            ),
            {
              title: t(
                "codex.localAccess.enableBeforeActivateTitle",
                "服务未启用",
              ),
              kind: "warning",
              okLabel: t(
                "codex.localAccess.enableAndActivateAction",
                "启用并切号",

View on GitHub (pinned to 1ed8b77992)

Solutions

Create/enable a local API service collection first so `localAccessCollection` is populated, then activate.
Reload the Codex accounts page to re-fetch the collection state.
If a specific `instanceId` was passed, verify that instance still exists and has a configured address.
Guard the UI button (disable it) when `localAccessCollection` is null instead of letting the call throw.

Example fix

// before
await handleActivateLocalAccess();
// after
if (!localAccessCollection) {
  setMessage({ text: t("codex.localAccess.testUnavailable"), tone: "warning" });
  return;
}
await handleActivateLocalAccess();

Defensive patterns

Strategy: type-guard

Validate before calling

if (!localAccessCollection || !localAccessCollection.enabled) {
  disableActivateButton();
}

Type guard

function canActivateLocalAccess(c: LocalAccessCollection | null | undefined): c is LocalAccessCollection {
  return !!c && typeof c.enabled === "boolean";
}

Try / catch

try {
  await handleActivateLocalAccess();
} catch (err) {
  if (err instanceof Error && err.message.includes("当前 API 服务地址不可用")) {
    openApiServiceConfigDialog();
  } else { throw err; }
}

Prevention

Load the collection state before rendering activate controls.
Disable the activate button when no collection exists.
Validate instanceId references on navigation.

When it happens

Trigger: Invoking activate-local-access (from the accounts page or with an `instanceId`) before any local access collection has been created/enabled, or after the collection data failed to load, so `localAccessCollection` is falsy at the top of the handler.

Common situations: Clicking "activate API service" on a fresh install before configuring a service address; the collection fetch failed silently earlier; an instance ID references a collection that was deleted.

Related errors

AI-assisted analysis of jlcodes99/cockpit-tools@1ed8b77992 (2026-09-05). Data as JSON: /api/errors/a0240f589ac43ab5. Report an issue: GitHub.