mihomo-party-org/clash-party · error

GLOBAL proxy not found

Error message

GLOBAL proxy not found

What it means

mihomoProxies fetches `/proxies` from the mihomo RESTful API and requires the reserved `GLOBAL` group to be present in the response, since the app's group/selector logic is built around it. If the API responds successfully but the proxy map lacks a `GLOBAL` entry, it throws this error because downstream consumers (runtime config, group switching) would otherwise crash on undefined.

Source

Thrown at src/main/core/mihomoApi.ts:256

  const instance = await getAxios()
  return await instance.delete('/connections')
}

export const mihomoRules = async (): Promise<IMihomoRulesInfo> => {
  const instance = await getAxios()
  return await instance.get('/rules')
}

export const mihomoRulesDisable = async (rules: Record<string, boolean>): Promise<void> => {
  const instance = await getAxios()
  return await instance.patch('/rules/disable', rules)
}

export const mihomoProxies = async (): Promise<IMihomoProxies> => {
  const instance = await getAxios()
  const proxies = (await instance.get('/proxies')) as IMihomoProxies
  if (!proxies.proxies['GLOBAL']) {
    throw new Error('GLOBAL proxy not found')
  }
  return proxies
}

function isMihomoGroup(proxy: IMihomoProxy | IMihomoGroup | undefined): proxy is IMihomoGroup {
  return Boolean(proxy && 'all' in proxy)
}

const PROVIDER_DETAIL_FETCH_THRESHOLD = 8

async function mihomoProxyProvider(name: string): Promise<IMihomoProxyProvider> {
  const instance = await getAxios()
  return await instance.get(`/providers/proxies/${encodeURIComponent(name)}`)
}

async function resolveProviderProxies(
  names: Set<string>,
  providerNames: Set<string>,

View on GitHub (pinned to 911e090537)

Solutions

  1. Confirm the external-controller address/port targets the running mihomo core (curl http://127.0.0.1:<port>/proxies) and that 'GLOBAL' appears in the JSON.
  2. Restart the mihomo core so it regenerates the full proxy set including GLOBAL.
  3. Update the core to current mihomo (Meta) — legacy Clash cores have divergent /proxies payloads.
  4. Check that a config with proxies actually loaded; a core started with an empty/invalid profile may expose no groups.

Example fix

// before: controller pointing at wrong/legacy core
externalController: '127.0.0.1:9090' // legacy clash

// after: run mihomo (Meta) core and match the port
externalController: '127.0.0.1:9097' // mihomo, verified via /version
Defensive patterns

Strategy: try-catch

Validate before calling

// probe the controller before relying on /proxies
const res = await axios.get(`http://${controller}/version`)
if (!String(res.data?.version ?? '').includes('meta')) {
  console.warn('Controller does not look like a mihomo (Meta) core; GLOBAL may be absent')
}

Type guard

function hasGlobal(p: IMihomoProxies): boolean {
  return Boolean(p && typeof p === 'object' && p.proxies && 'GLOBAL' in p.proxies)
}

Try / catch

try {
  const proxies = await mihomoProxies()
} catch (e) {
  if ((e as Error).message === 'GLOBAL proxy not found') {
    await restartCore() // regenerate full proxy set
    return mihomoProxies()
  }
  throw e
}

Prevention

When it happens

Trigger: Calling mihomoProxies (directly or via the `proxies`/`runtime` IPC handlers) while the connected core's `/proxies` response contains no `GLOBAL` key — e.g. querying an external controller of a non-mihomo/older Clash core, hitting a wrong port where another service responds, or a core version whose response shape differs.

Common situations: Pointing the app's external-controller at a stale Clash core (premium/legacy) that doesn't expose GLOBAL the same way; controller URL misconfigured to a different app; core upgraded/downgraded with an incompatible API; transient core restart mid-request returning an empty/partial payload.

Related errors

AI-assisted analysis of mihomo-party-org/clash-party@911e090537 (2026-08-30). Data as JSON: /api/errors/73ed3f19e49eba2c. Report an issue: GitHub.