synergycodes/ng-diagram/ng-diagram-troubleshooting

Troubleshooting ng-diagram

Start from a symptom or a console message: run the first checks, find the symptom below, then open the skill that owns the fix. Every message the library can print is in references/console-messages.md; bugs fixed by an upgrade are in references/upgrade-fixes.md.

Rules

• Check the installed version first (node_modules/ng-diagram/package.json or the lockfile). Many symptoms are bugs fixed in 1.2–1.4; compare with "Fixed in a later version" below.
• Copy the exact console text and search references/console-messages.md for it. Most library messages start with [ngDiagram]; for a multi-line message, search its first line.
• Go through "First checks" before deep debugging. Most reports are one of them.
• Confirm every API name in node_modules/ng-diagram/ng-diagram.d.ts before you suggest code. Some docs pages and older examples do not compile against 1.4.0.
• Never "fix" by writing system-owned fields (measuredPorts, measuredBounds, measuredLabels, computedZIndex, computedHidden, sourcePosition/targetPosition of connected ends, points of auto-routed edges, size of auto-sized nodes). The library recomputes them and your value is lost.
• Never hide nodes, edges, ports or the diagram with CSS display: none. Hidden elements measure 0 × 0, initialization waits 2 to 4 seconds and logs measurement timeouts. Use the hidden flag or inputs (ng-diagram-visibility).

First checks

Check these in order; each line says how to see it quickly.

1. Global styles. getComputedStyle(document.documentElement).getPropertyValue('--ngd-node-border-radius') is empty when ng-diagram/styles.css is not imported in the global stylesheet. → ng-diagram-setup
2. `provideNgDiagram()` scope. It must be in providers of the component that renders <ng-diagram> (or an ancestor), and every component or service that injects an ng-diagram service must sit below it. Otherwise: NgDiagram services are not available… or NG0201 / NullInjectorError. → ng-diagram-setup
3. Container size. <ng-diagram> is 100% of its parent; a parent without a height shows nothing and logs nothing. Look at the element's height in DevTools. → ng-diagram-setup
4. One model per diagram. Create it once with initializeModel() (custom adapters: initializeModelAdapter()). Re-creating it re-initializes the diagram; binding a model again after its diagram was destroyed gives an empty, frozen diagram. → ng-diagram-model-init, ng-diagram-persistence
5. No calls before init. Service calls in the host's constructor or ngOnInit, or a toolbar that binds canZoomIn(), throw [ngDiagram] Library engine not initialized yet. Move them into (diagramInit) or guard with isInitialized(). → ng-diagram-model-init
6. Runtime config. <ng-diagram> reads [config] (except the watermark keys) and [middlewares] only when a model is initialized. At runtime use NgDiagramService.updateConfig() and registerMiddleware(); a few keys are read only at engine start even then (ng-diagram-config).
7. Await, then read with getters. After await on a service call, getNodeById(), getEdgeById() and getModel() are fresh; the nodes() / edges() / metadata() signals refresh with change detection and can lag, also in event handlers. → ng-diagram-state-updates
8. Nothing hidden with CSS. display: none on nodes, ports, labels or a parent of the diagram (an inactive tab, a collapsed panel) shows as Measurement timeout reached warnings and a diagram that appears after 2 to 4 seconds. → ng-diagram-visibility
9. Port ids. sourcePort / targetPort must name a port that the node template renders (the default node has port-left and port-right). A wrong id draws nothing and logs nothing; compare with getNodeById(id)?.measuredPorts?.map((p) => p.id). → ng-diagram-ports
10. Only the background goes inside `<ng-diagram>`. It projects <ng-diagram-background> and nothing else; a minimap, toolbar or overlay placed inside is not rendered. Put them next to it in a position: relative wrapper. → ng-diagram-setup, ng-diagram-minimap

Symptom router

The owning skill has the full table for its area.

Setup and rendering

Initialization and timing

Model updates and state

Nodes, ports and measurement

Edges and linking

Interaction and events

Viewport and export