What causes "useGroups must be used within an GroupsProvider" in mihomo-party-org/clash-party?

Wrap the consuming component tree with at an ancestor level (e.g. in App.tsx).

mihomo-party-org/clash-party · error · Error

useGroups must be used within an GroupsProvider

Error message

useGroups must be used within an GroupsProvider

What it means

useGroups is a React context consumer hook for the Groups context. It throws when called outside of a GroupsProvider because the context value is undefined — the library intentionally fails fast instead of returning null and causing a confusing downstream crash. This is a standard React context safety pattern.

Source

Thrown at src/renderer/src/hooks/use-groups.tsx:49

      mutate()
    }
    window.electron.ipcRenderer.on('groupsUpdated', handler)
    return (): void => {
      window.electron.ipcRenderer.removeListener('groupsUpdated', handler)
    }
  }, [mutate])

  return (
    <GroupsContext.Provider value={{ groups, mutate, showHidden, setShowHidden }}>
      {children}
    </GroupsContext.Provider>
  )
}

export const useGroups = (): GroupsContextType => {
  const context = useContext(GroupsContext)
  if (context === undefined) {
    throw new Error('useGroups must be used within an GroupsProvider')
  }
  return context
}

View on GitHub (pinned to 911e090537)

Solutions

Wrap the consuming component tree with <GroupsProvider> at an ancestor level (e.g. in App.tsx).
In tests, wrap with <GroupsProvider> (or a mock provider) inside render/renderHook.
If the component legitimately renders outside the tree, use a React portal that stays inside the provider's DOM/react subtree.
Re-export a safe wrapper hook that returns null and let callers handle the undefined case if the provider is optional in your app.

Example fix

// before
export default function GroupList() {
  const { groups } = useGroups()
  return <div>{groups.map(g => g.name)}</div>
}
// after
export default function App() {
  return (
    <GroupsProvider>
      <GroupList />
    </GroupsProvider>
  )
}

Defensive patterns

Strategy: validation

Validate before calling

// In the component, guard before consuming:
const context = React.useContext(GroupsContext)
if (context === undefined) {
  // render fallback or return early instead of calling the throwing hook
  return <GroupsUnavailable />
}

Type guard

function hasGroupsContext(c: GroupsContextType | undefined): c is GroupsContextType {
  return c !== undefined
}

Prevention

Always render consumers inside <GroupsProvider> (verify with React DevTools component tree).
Create a shared test wrapper that includes all app providers and reuse it in every render/renderHook call.
Keep providers mounted unconditionally at the app root rather than deep in conditional layouts.
Never call context hooks from module scope or plain (non-component) functions.

When it happens

Trigger: Calling useGroups() in a component that is not rendered as a descendant of <GroupsProvider>, or calling it in a module/top-level scope before the provider tree exists, or rendering the consuming component in a separate React root that does not include the provider.

Common situations: A component is moved into a portal, dialog, or lazily-rendered subtree mounted outside the provider; test renders (e.g. renderHook / RTL render) that forget to wrap with GroupsProvider; hooking it into a utility function invoked outside React render.

Related errors

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