What causes "useModelContext must be used within a ModelProvider" in iflytek/astron-agent?

Wrap the consuming component tree with at the nearest common ancestor (page or route layout).

iflytek/astron-agent · error · Error

useModelContext must be used within a ModelProvider

Error message

useModelContext must be used within a ModelProvider

What it means

`useModelContext` reads React context created by the ModelProvider. The context object has no default value (undefined), so if the hook runs while no `<ModelProvider>` ancestor exists, the code throws 'useModelContext must be used within a ModelProvider'. This is a standard context-guard pattern to give a clear message instead of a cryptic undefined-destructure crash later.

Solutions

Wrap the consuming component tree with <ModelProvider> at the nearest common ancestor (page or route layout).
Check render order: the provider must be an ancestor, not a sibling or child, of the consumer.
In tests/stories, wrap with the provider in the render helper.
If undefined is legitimate, create a variant hook that returns a default context instead of throwing.

Example fix

// before
<ModelDetailPage /> // throws: no provider

// after
<ModelProvider>
  <ModelDetailPage />
</ModelProvider>

Defensive patterns

Strategy: try-catch

Validate before calling

// at module scope
customHooks.push(() => {
  try { useContextForTest(ModelContext); } catch { console.warn('ModelProvider missing'); }
});

Type guard

const useModelContextSafe = (): ModelContextValue | undefined => useContext(ModelContext);

Try / catch

let value: ModelContextValue;
try {
  value = useModelContext();
} catch {
  value = DEFAULT_MODEL_CONTEXT; // or render fallback UI
}

Prevention

Wrap each route/page that uses model hooks with <ModelProvider> in a shared layout.
Add a test-render helper that always includes required providers.
Keep provider placement in route-level components, not leaf components.
Enable ESLint react-context rules or code review checks for provider usage.

When it happens

Trigger: Calling useModelContext() from a component rendered outside <ModelProvider>, or inside a component tree where the provider is conditionally unmounted, or in a separate React root (portal/render) that doesn't inherit the provider.

Common situations: Reusing a model-aware component in a new route/page where the provider was forgotten; moving a component into a story/test without the provider wrapper; provider placed below the consumer in the tree (context flows downward only).

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/89a6bcdcb08f1e27. Report an issue: GitHub.

Appendix: source

Thrown at console/frontend/src/pages/model-management/context/model-context.tsx:193

  const value = useMemo(
    () => ({
      state,
      actions,
    }),
    [state, actions]
  );

  return (
    <ModelContext.Provider value={value}>{children}</ModelContext.Provider>
  );
};

// Hook
export const useModelContext = (): ModelContextValue => {
  const context = useContext(ModelContext);
  if (context === undefined) {
    throw new Error('useModelContext must be used within a ModelProvider');
  }
  return context;
};

View on GitHub (pinned to 5e758547a8)