{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "troubleshooting-docs",
  "title": "Troubleshooting",
  "description": "Diagnose common Plate setup and runtime issues.",
  "files": [
    {
      "path": "../../content/docs/(guides)/troubleshooting.mdx",
      "content": "---\ntitle: Troubleshooting\ndescription: Diagnose common Plate setup and runtime issues.\n---\n\nMost Plate issues come from version skew, duplicate React/Slate runtimes, or\ncrossing the server/client import boundary. Start with package alignment, then\ncheck runtime ownership, then inspect plugin resolution with `DebugPlugin`.\n\n## Start Here\n\n| Symptom | First check |\n| --- | --- |\n| Invalid hook call, null dispatcher, or React hook crashes. | Duplicate `react` / `react-dom` or mixed package-manager installs. |\n| Plugins render as plain text or components do not attach. | Missing plugin, wrong `/react` versus base import, or wrong component map. |\n| Server Component crashes on import. | A Server Component imported `platejs/react` or `@platejs/*/react`. |\n| `OPTION_UNDEFINED` in the console. | Code reads or writes an option that is not declared in the plugin. |\n| `PLUGIN_DEPENDENCY_MISSING` in the console. | A plugin dependency key is not present in the editor plugin list. |\n| Markdown, HTML, or static rendering misses nodes. | The static/base plugin kit does not include the serializer or node plugin. |\n\nUse the focused guide when the issue belongs to one area:\n\n| Area | Guide |\n| --- | --- |\n| Editor creation and options | [Editor](/docs/editor) |\n| Plugin configuration | [Plugin](/docs/plugin) |\n| Plugin option state | [Plugin Context](/docs/plugin-context) |\n| Debug logging | [Debugging](/docs/debugging) |\n| Server Components | [RSC](/docs/installation/rsc) |\n| Static rendering | [Static Rendering](/docs/static) |\n\n## Align Plate Packages\n\nKeep `platejs` and every `@platejs/*` package on the same release family.\n`depset` is the fastest way to update a project that already has several Plate\npackages installed.\n\n```bash\nnpx depset@latest @platejs --latest --install --yes\nnpx depset@latest platejs --latest --install --yes\n```\n\nFor pnpm projects:\n\n```bash\npnpm dlx depset@latest @platejs --latest --install --yes\npnpm dlx depset@latest platejs --latest --install --yes\n```\n\nThen inspect what actually resolved.\n\n```bash\nnpm ls platejs @platejs/core @platejs/slate react react-dom slate slate-dom slate-react\n```\n\n```bash\npnpm why platejs\npnpm why @platejs/core\npnpm why @platejs/slate\npnpm why react react-dom slate slate-dom slate-react\n```\n\nIf the tree shows multiple Plate majors, align the Plate packages first. If it\nshows multiple React or Slate copies, fix the package that pulls the extra copy\ninstead of papering over the tree with a random override.\n\n## Fix Runtime Boundaries\n\nUse React entrypoints only in client-side editor code.\n\n| Runtime | Import from |\n| --- | --- |\n| Editable React editor | `platejs/react`, `@platejs/*/react` |\n| Server Component static output | `platejs/static`, `platejs`, `@platejs/*` |\n| Node script or route handler without React UI | `platejs`, `@platejs/*` |\n\n<Callout type=\"warning\" title=\"No React plugins on the server\">\n  Server Components and Node scripts should not import `platejs/react` or\n  `@platejs/*/react`. Use base plugins such as `BaseH1Plugin` from\n  `@platejs/basic-nodes`, not `H1Plugin` from `@platejs/basic-nodes/react`.\n</Callout>\n\nIf a server route only needs serialization or transforms, use the Node path from\n[Node.js](/docs/installation/node). If it renders read-only React output, use\n[Static Rendering](/docs/static).\n\n## Check Component Wiring\n\nWhen a node appears as plain text or a default `div`, check the component path.\n\n```tsx title=\"components/editor/plugins.tsx\" showLineNumbers\nimport { H1Plugin } from '@platejs/basic-nodes/react';\n\nimport { H1Element } from '@/components/ui/heading-node';\n\nexport const plugins = [H1Plugin.withComponent(H1Element)];\n```\n\nFor copied Plate UI kits, inspect the kit that owns the feature before adding\nmanual component overrides. Feature kits usually wire plugins, components,\nshortcuts, and options together.\n\n| Component surface | Guide |\n| --- | --- |\n| Copied registry components | [Plate UI](/docs/installation/plate-ui) |\n| Feature-owned kits | [Feature Kits](/docs/feature-kits) |\n| Manual node components | [Plugin Components](/docs/plugin-components) |\n\n## Inspect Plugin Resolution\n\nEnable `DebugPlugin` when plugin options, dependencies, or runtime behavior do\nnot match what the editor receives.\n\n```tsx title=\"components/editor/plugins.tsx\" showLineNumbers\nimport { DebugPlugin } from 'platejs';\n\nexport const plugins = [\n  DebugPlugin.configure({\n    options: {\n      logLevel: 'warn',\n    },\n  }),\n];\n```\n\nCommon debug errors:\n\n| Message | Meaning |\n| --- | --- |\n| `OPTION_UNDEFINED` | `editor.getOption`, `editor.setOption`, or plugin context used an option key missing from `plugin.options`. |\n| `PLUGIN_DEPENDENCY_MISSING` | A plugin lists a dependency key that is not registered. |\n\nUse [Plugin](/docs/plugin#advanced-plugin-configuration) to check `dependencies`,\n`priority`, `enabled`, `plugins`, and `override.*` behavior.\n\n## Reset The Install\n\nWhen the dependency tree looks correct but the runtime still behaves like two\nReact or Slate copies are loaded, reinstall from the existing lockfile.\n\n```bash\nrm -rf node_modules\nnpm install\n```\n\n```bash\nrm -rf node_modules\npnpm install\n```\n\nDelete the lockfile only when you intentionally want a fresh dependency\nresolution. That is a package-management decision, not a Plate fix.\n\n## Report A Reproduction\n\nWhen you open an issue, include the smallest editor that reproduces the problem:\n\n- Package manager and lockfile type.\n- Output from the relevant `npm ls` or `pnpm why` commands.\n- The plugin list passed to `usePlateEditor`, `createPlateEditor`,\n  `createSlateEditor`, or `createStaticEditor`.\n- The failing value, if the issue depends on document content.\n- The exact error message from `DebugPlugin` or the browser console.\n\nSmall reproductions beat screenshots. The package tree and plugin list usually\ntell the story.\n",
      "type": "registry:file",
      "target": "content/docs/plate/(guides)/troubleshooting.mdx"
    }
  ],
  "type": "registry:file"
}