Plate
PlateEditorsTemplates
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
  • Authored Changes
  • Performance
  • Static Rendering
  • HTML
  • Markdown
  • Form
  • TypeScript
  • Debugging
  • Unit Testing
  • Browser
  • Troubleshooting
  • Locations
  • Transactions
  • Serializing
  • Roots
  • Document Meta
  • Clipboard and Paste
  • Decorations, annotations, and widgets
  • Schema
  • History
  • Pagination
  • Annotations
  • DOM Coverage
  • External Text Views
  • Virtualized Rendering

Troubleshooting

PreviousNext

Diagnose common Plate setup and runtime issues.

Most Plate issues come from version skew, duplicate React/Plate 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.
BrowserLocations

On This Page

Start hereUpdate PlateFix runtime boundariesCheck component wiringInspect plugin resolutionReset the installReport a reproduction
Build your editor
Production-ready AI template and reusable components.
Get all-access
Server Component crashes on import.
A Server Component imported platejs/react or platejs/<feature>/react.
requires disabled plugin in the console.An explicitly disabled plugin is required by an enabled plugin.
Pass a plugin descriptor, not its name.A dependency contains a string instead of a plugin descriptor.
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

Update Plate

Plate editor features ship from one platejs package. Use the Plate CLI to update it without managing a set of feature package versions.

pnpm dlx @platejs/cli@latest deps platejs --latest --install --yes
pnpm dlx @platejs/cli@latest deps platejs --latest --install --yes

For pnpm projects:

pnpm dlx @platejs/cli@latest deps platejs --latest --install --yes
pnpm dlx @platejs/cli@latest deps platejs --latest --install --yes

Then inspect what actually resolved.

npm ls platejs react react-dom
npm ls platejs react react-dom
pnpm why platejs
pnpm why react react-dom
pnpm why platejs
pnpm why react react-dom

If the tree shows multiple Plate majors, align the Plate packages first. If it shows multiple React 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/<feature>/react
Server Component static outputplatejs/static, platejs, platejs/<feature>
Node script or route handler without React UIplatejs, platejs/<feature>
No React plugins on the server

Server Components and Node scripts should not import platejs/react or platejs/<feature>/react. Use base plugins such as BaseHeadingPlugin from platejs, not HeadingPlugin from platejs/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/react';
 
import { HeadingElement } from '@/components/editor/heading';
 
export const plugins = [HeadingPlugin.configure({ component: HeadingElement })];
components/editor/plugins.tsx
import { HeadingPlugin } from 'platejs/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
requires disabled pluginAn enabled plugin requires a dependency that the app disabled.
Circular plugin dependencyPlugin dependencies form a cycle.

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 Plate 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 useCreateEditor, createEditor, 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.