Troubleshooting · Building

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	Name mismatch: the backend names the component differently from the name `sdk.registerComponent` gave it, and Vue stays silent	Frontend layer
A module's composable or util is not defined after an `@antelopejs/dms-frontend` upgrade	The release with module-declared auto-imports auto-imports nothing from a module without `dms.frontend.build.ts`, and never its `app/build/`	Frontend layer
A component renders blank after an `@antelopejs/dms-frontend` upgrade, its name sent without the module's prefix	From 0.5 a module's `componentPrefix` is part of the name and a leading `Dms` is no longer dropped: the backend sends `Table` where the registered name is `DmsTable`	Frontend layer
You edit layer code but the dashboard shows the old version	The dev server serves the materialized layer copy, and a watcher missed the edit	Frontend layer
Boot fails with `Unresolved interface dependencies: <module> requires <package>`	A dependency carrying an `antelopeJs` manifest that no loaded module declares in `implements` — a runtime package other modules import from must declare its own name	Distributable module
The backend builds clean but the page 500s when opened	A Vue template or compile error in the layer — `tsc` never compiles the frontend module	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
With several tabs open, pages hang loading and requests stay pending	The browser's six HTTP/1.1 connections per host are taken by long-lived streams: the dashboard is served over plain HTTP from a host name other than `localhost`, so the tabs cannot share their realtime stream	Deployment
Live pages poll instead of updating live; `POST /api/realtime/session` answers `{ ok: false }`	A proxy between the browser and the backend drops the `x-realtime-connection` header	Deployment
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 `dms.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 `<DmsFoo>`	A different full component name, or your layer's `priority` is too low: higher numbers register first	Frontend layer

Layer source edits normally propagate through the development watcher. If an edit stays stale, restart the backend first, then the frontend (Project setup). For a blank pane, check both the browser console and the full registered component name: a name mismatch can render an empty div without an error.