Troubleshooting
The recurring failure modes of DMS development look alike from the outside — a blank pane, a 404, a stale screen — while their causes live in different parts of the stack. Each symptom below maps to its cause and to the section that explains it; the linked sections own the full story.
| Symptom | Cause | Explained in |
|---|---|---|
| A custom component renders blank, no console error | Auto-import name mismatch: with pathPrefix: false the name is prefix + filename only, and Vue stays silent | Frontend layer |
A CustomComponent pane is blank, console shows a [resolveCmsComponent] warning | The backend string and the registered component name disagree after normalization; the catch-all renders a div | Custom component |
| You edit layer code but the dashboard shows the old version | The dev server serves the materialized .acms copy, and a watcher missed the edit | Frontend layer |
| The backend builds clean but the page 500s when opened | A Vue template or compile error in the layer — tsc never compiles the Nuxt layer | Frontend layer |
A link or router.push to a module page 404s | The path omits the /modules/<moduleId> prefix module pages mount under | Distributable module |
| The backend builds and starts but the dashboard never lists your page | The pages barrel is never imported, so the @RegisterPage decorators never run | Pages & components |
| Realtime events, presence, or notifications don't reach users on another instance | The in-memory realtime driver — it does not cross process boundaries; multi-instance needs Redis | Configuration |
| Publishing to a topic reaches no subscriber | The topic is not registered on any page — topics are page-bound | Backend services |
The UI shows a raw cms.x.y key instead of text | The $-prefixed key is missing from one or more locale files | Localization |
Your layer's Foo.vue doesn't override the base <CmsFoo> | A different prefix, or your layer loses the priority precedence (lower number wins) | Frontend layer |
Two habits shortcut most of these. After editing layer source, full-restart both processes — backend first, then frontend — before debugging anything that looks new (Project setup). And when a pane is blank, check the browser console first: a resolver warning distinguishes a name mismatch from a genuinely empty component.
Deployment
Run the DMS in production — build both processes, start them in the right order, and check off the secrets and multi-instance requirements.
Built-in authentication
The complete auth system the DMS ships — sessions and token rotation, invite-based signup, login with tenant selection, two-factor, email validation, and password recovery.