From zbeyens. The source code is available on GitHub.

Plate
PlatePliteEditorsTemplates
GitHub16kGitHub
DiscordDiscord
  • Feature Kits
  • Plugin
    • Plugin Methods
    • Plugin Shortcuts
    • Plugin Context
    • Plugin Components
    • Plugin Rules
    • Editing Behavior
    • Plugin Input Rules
  • Editor
    • Editor Methods
    • Controlled Value
  • Performance
  • Static Rendering
  • HTML
  • Markdown
  • Form
  • TypeScript
  • Debugging
  • Unit Testing
  • Browser
  • Troubleshooting

Troubleshooting

PreviousNext

Diagnose common Plate setup and runtime issues.

Most Plate issues come from version skew, duplicate React/Plite runtimes, or crossing the server/client import boundary. Start with package alignment, then check runtime ownership, then inspect plugin resolution with DebugPlugin.

Start Here

SymptomFirst check
Invalid hook call, null dispatcher, or React hook crashes.Duplicate react / react-dom or mixed package-manager installs.
Plugins render as plain text or components do not attach.Missing plugin, wrong /react versus base import, or wrong component map.
Server Component crashes on import.
BrowserOverview

On This Page

Start HereAlign Plate PackagesFix Runtime BoundariesCheck Component WiringInspect Plugin ResolutionReset The InstallReport A Reproduction
Build your editor
Production-ready AI template and reusable components.
Get all-access
A Server Component imported platejs/react or @platejs/*/react.
OPTION_UNDEFINED in the console.Code reads or writes an option that is not declared in the plugin.
PLUGIN_DEPENDENCY_MISSING in the console.A plugin dependency name is not present in the editor plugin list.
Markdown, HTML, or static rendering misses nodes.The static/base plugin kit does not include the serializer or node plugin.

Use the focused guide when the issue belongs to one area:

AreaGuide
Editor creation and optionsEditor
Plugin configurationPlugin
Plugin store statePlugin Context
Debug loggingDebugging
Server ComponentsRSC
Static renderingStatic Rendering

Align Plate Packages

Keep platejs and every @platejs/* package on the same release family. depset is the fastest way to update a project that already has several Plate packages installed.

pnpm dlx depset@latest @platejs --latest --install --yes
npx depset@latest platejs --latest --install --yes
pnpm dlx depset@latest @platejs --latest --install --yes
npx depset@latest platejs --latest --install --yes

For pnpm projects:

pnpm dlx depset@latest @platejs --latest --install --yes
pnpm dlx depset@latest platejs --latest --install --yes
pnpm dlx depset@latest @platejs --latest --install --yes
pnpm dlx depset@latest platejs --latest --install --yes

Then inspect what actually resolved.

npm ls platejs @platejs/core @platejs/plite @platejs/plite-dom @platejs/plite-react react react-dom
npm ls platejs @platejs/core @platejs/plite @platejs/plite-dom @platejs/plite-react react react-dom
pnpm why platejs
pnpm why @platejs/core
pnpm why @platejs/plite
pnpm why @platejs/plite-dom @platejs/plite-react
pnpm why react react-dom
pnpm why platejs
pnpm why @platejs/core
pnpm why @platejs/plite
pnpm why @platejs/plite-dom @platejs/plite-react
pnpm why react react-dom

If the tree shows multiple Plate majors, align the Plate packages first. If it shows multiple React or Plite copies, fix the package that pulls the extra copy instead of papering over the tree with a random override.

Fix Runtime Boundaries

Use React entrypoints only in client-side editor code.

RuntimeImport from
Editable React editorplatejs/react, @platejs/*/react
Server Component static outputplatejs/static, platejs, @platejs/*
Node script or route handler without React UIplatejs, @platejs/*
No React plugins on the server

Server Components and Node scripts should not import platejs/react or @platejs/*/react. Use base plugins such as BaseHeadingPlugin from @platejs/basic-nodes, not HeadingPlugin from @platejs/basic-nodes/react.

If a server route only needs serialization or transforms, use the Node path from Node.js. If it renders read-only React output, use Static Rendering.

Check Component Wiring

When a node appears as plain text or a default div, check the component path.

components/editor/plugins.tsx
import { HeadingPlugin } from '@platejs/basic-nodes/react';
 
import { HeadingElement } from '@/components/editor/heading';
 
export const plugins = [HeadingPlugin.configure({ component: HeadingElement })];
components/editor/plugins.tsx
import { HeadingPlugin } from '@platejs/basic-nodes/react';
 
import { HeadingElement } from '@/components/editor/heading';
 
export const plugins = [HeadingPlugin.configure({ component: HeadingElement })];

For copied Plate UI kits, inspect the kit that owns the feature before adding manual component overrides. Feature kits usually wire plugins, components, shortcuts, and options together.

Component surfaceGuide
Copied registry componentsPlate UI
Feature-owned kitsFeature Kits
Manual node componentsPlugin Components

Inspect Plugin Resolution

Enable DebugPlugin when plugin state, dependencies, or runtime behavior do not match what the editor receives.

components/editor/plugins.tsx
import { DebugPlugin } from 'platejs';
 
export const plugins = [
  DebugPlugin.configure({
    initialState: {
      logLevel: 'warn',
    },
  }),
];
components/editor/plugins.tsx
import { DebugPlugin } from 'platejs';
 
export const plugins = [
  DebugPlugin.configure({
    initialState: {
      logLevel: 'warn',
    },
  }),
];

Common debug errors:

MessageMeaning
PLUGIN_DEPENDENCY_MISSINGA plugin lists a dependency name that is not registered.

Use Plugin to check dependencies, enabled, and override.* behavior.

Reset The Install

When the dependency tree looks correct but the runtime still behaves like two React or Plite copies are loaded, reinstall from the existing lockfile.

rm -rf node_modules
npm install
rm -rf node_modules
npm install
rm -rf node_modules
pnpm install
rm -rf node_modules
pnpm install

Delete the lockfile only when you intentionally want a fresh dependency resolution. That is a package-management decision, not a Plate fix.

Report A Reproduction

When you open an issue, include the smallest editor that reproduces the problem:

  • Package manager and lockfile type.
  • Output from the relevant npm ls or pnpm why commands.
  • The plugin list passed to usePlateEditor, createPlateEditor, createBaseEditor, or createStaticEditor.
  • The failing value, if the issue depends on document content.
  • The exact error message from DebugPlugin or the browser console.

Small reproductions beat screenshots. The package tree and plugin list usually tell the story.