{"record":{"id":"445b293653a324f2","repo":"mastra-ai/mastra","slug":"usejsonschemaform-must-be-used-within-a-jsonschema","errorCode":null,"errorMessage":"useJSONSchemaForm must be used within a JSONSchemaForm.Root","messagePattern":"useJSONSchemaForm must be used within a JSONSchemaForm\\.Root","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playground-ui/src/ds/components/JSONSchemaForm/json-schema-form-context.tsx","lineNumber":27,"sourceCode":"  maxDepth: number;\n}\n\nconst JSONSchemaFormContext = React.createContext<JSONSchemaFormContextValue | null>(null);\n\nexport function JSONSchemaFormProvider({\n  children,\n  value,\n}: {\n  children: React.ReactNode;\n  value: JSONSchemaFormContextValue;\n}) {\n  return <JSONSchemaFormContext.Provider value={value}>{children}</JSONSchemaFormContext.Provider>;\n}\n\nexport function useJSONSchemaForm(): JSONSchemaFormContextValue {\n  const context = React.useContext(JSONSchemaFormContext);\n  if (!context) {\n    throw new Error('useJSONSchemaForm must be used within a JSONSchemaForm.Root');\n  }\n  return context;\n}\n","sourceCodeStart":9,"sourceCodeEnd":31,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/playground-ui/src/ds/components/JSONSchemaForm/json-schema-form-context.tsx#L9-L31","documentation":"useJSONSchemaForm returns the shared form state (addField, fields, updateField, maxDepth, etc.) from JSONSchemaFormContext, which only JSONSchemaForm.Root provides. Outside a Root the context is null and the hook throws, guaranteeing form subcomponents always have valid form state.","triggerScenarios":"Calling useJSONSchemaForm in a component rendered outside <JSONSchemaForm.Root> — e.g. a custom add-field button or field list placed outside the Root, or a child lifted into a separate tree (portal/modal without its own Root).","commonSituations":"Building custom form chrome (toolbar, add field button) and forgetting to place it inside Root; rendering the form's field list in a parent component for layout reasons; storybook examples mounting subcomponents in isolation.","solutions":["Move the consumer inside <JSONSchemaForm.Root schema={...}>...</JSONSchemaForm.Root>.","If the UI must live outside the Root element, lift the Root higher so the whole form subtree is covered, or pass the needed callbacks as explicit props instead of using the hook.","For modals/portals, render them within Root's subtree (React context crosses portals, but not tree boundaries — keep Root as an ancestor).","Add a useMaybeJSONSchemaForm-style nullable accessor if optional usage is a real requirement."],"exampleFix":"// before\n<AddFieldButton /> // outside Root\n// after\n<JSONSchemaForm.Root schema={schema} onSubmit={submit}>\n  <AddFieldButton />\n</JSONSchemaForm.Root>","handlingStrategy":"try-catch","validationCode":"// Ensure JSONSchemaForm.Root wraps all consumers of useJSONSchemaForm.\n// Optional access pattern:\nconst ctx = React.useContext(JSONSchemaFormContext);\nif (!ctx) console.warn('useJSONSchemaForm consumer must be nested in JSONSchemaForm.Root');","typeGuard":"function hasFormContext(c: JSONSchemaFormContextValue | null): c is JSONSchemaFormContextValue {\n  return c !== null;\n}","tryCatchPattern":"// Hooks cannot be try/catch-wrapped; use an error boundary at the form section level:\n<ErrorBoundary fallback={<InvalidFormUsage /> }>\n  <MyAddFieldButton />\n</ErrorBoundary>","preventionTips":["Nest all form chrome (toolbars, field lists) inside JSONSchemaForm.Root.","Pass addField/updateField as explicit props when a control must live outside the form tree.","Render modals/portals as descendants of Root so context still flows.","Differentiate Root-level (useJSONSchemaForm) vs Field-level (useJSONSchemaFormField) hooks when choosing which to call."],"tags":["react","context","compound-components","json-schema","playground-ui"],"backgroundTag":"missing-react-context-provider","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}