Something not working?
Five things account for most of what gets reported, and none of them is a bug. Start there, then report what is left.
Skip to reporting if you have already been through them.
Five things worth checking first.
Four of these are configuration rather than bugs. The fifth is the one real failure mode the payload can tell you about itself, so it is worth knowing what to look for.
- The editor never shows up
- It has to be mounted inside <body>, and your dev check has to actually be true. In Next.js, process.env.NODE_ENV is 'development' only under next dev. Try the floating button's shortcut too, since the button can be dragged off to a corner you are not looking at.
- Saving does nothing, or 404s
- The handlers 404 outside development by design, and both sides have to agree on the path. If you moved the route, pass the same value to the component: <VisualEditor endpoint="/__dev/edits" />.
- Every edit has source: null
- That means the Vite plugin did not run. It has to come before react() in the plugins array, and it needs a TypeScript with a JS parser. TypeScript 7 dropped in-memory parsing, so on 7 you hand it a 5.x compiler yourself: visualEditorSource({ typescript }).
- No Component section on an element
- The manifest comes from scanning cva() definitions under components and src/components. Different layout means different roots: createVisualEditsHandlers({ components: { roots: ['app/ui'] } }). Not using cva at all? Supply the manifest yourself.
- The edit keeps landing on the wrong element
- Look for selectorAmbiguous: true on the entry. The selector is a position in the DOM, so a list that reorders between sessions can hand your edit to the neighbour. Source stamping fixes it where the stamp names one element, and sourceAmbiguous: true says when it does not. On anything you edit often, a data-testid is the anchor that never moves.
Still broken?
Then it is worth an issue. Bugs go to GitHub, where they stay searchable and where you can see whether someone already hit the same thing.
No GitHub account? Write to hi@marcosguerreros.es with the same details the issue form asks for.
What makes a report I can act on.
The issue form is already filled with this. The two that save the most time are the framework you are on and the entry from edits.json that came out wrong, because almost every real bug is either in element identification or in what the payload said about it.
If the editor produced nothing at all, the browser console is the next best thing. Every save is also logged there as [AI-EDIT-REQUEST].
{
"url": "http://localhost:3000/dashboard",
"selector": "body > div:nth-child(2) > button",
"selectorAmbiguous": true,
"tagName": "BUTTON",
"className": "btn btn-primary",
"source": "src/components/Button.tsx:42:7",
"componentStack": ["Button", "ProjectCard"],
"styles": { "padding": { "before": "8px", "after": "12px" } }
}Found a security problem?
Do not open a public issue. Mail hi@marcosguerreros.es directly. The editor is dev-only and its endpoint 404s outside development, so the blast radius is small by design, but a way around either of those guards is worth telling me about quietly first.
No checkbox here. This one is not a configuration mistake.