Diagram - Troubleshooting
Diagnose setup, ownership, policy, geometry and transport failures.
Start with the operation result and the active owner. Keep the current valid store while fixing a rejected candidate. A diagnostic describes a specific failure; bypassing validation or casting the result to success cannot repair it.
#Render and composition
| Symptom | Check | Recovery |
|---|---|---|
| Empty canvas | Required store/page, valid page ID, viewport height, scene diagnostics | Validate the candidate, select an existing page and give the viewport measurable height |
| Missing custom node content | Matching type/fallback definition and registration under the same root | Mount Diagram.NodeDef with the matching node-type, and render component content inside its slot |
| Missing symbol / placeholder | Root registry and explicit contentAvailability | Register the supported symbol/type or show the recoverable placeholder; do not invent a serialized component |
| Injection error in a control | Root/node/workspace ancestor | Move the part under its required owner; use DiagramWorkspaceHost for independent Pages/Layers controls |
| Inspector does not follow selection | Duplicate model provider or wrong root | Reuse the root-provided DiagramSelectionInspectorModel |
| Unstyled copied controls | Shared CSS, chosen preset's dependency imports, application scope | Load theme then structure then overrides; copy referenced files |
| Import cannot resolve | Public optional entry or copied application alias | Use Imports; avoid private/ɵ paths |
| License message | Application's own key and client license setup | Configure the workspace license provider separately from model validation |
The primary entry's DiagramNode/DiagramConnector/DiagramLabel names refer
to Vue parts. Use the corresponding ...Record aliases for authored data.
The Diagram namespace does not include optional capability parts or copied UI parts.
The canonical ancestor/import/projection matrix is
UI parts.
#Model and mutation
| Diagnostic / state | Likely cause | Recovery |
|---|---|---|
invalid-schema, unsupported-version | Wrong model shape/version or unsupported field | Construct the documented schema or apply an explicit application migration |
duplicate-id, invalid-id | Colliding or invalid authored identities | Assign distinct IDs across records/labels/ports; retain identity for updates |
invalid-reference, ownership-cycle | Missing page/layer/parent/endpoint or cyclic ownership | Repair references atomically or use the structural editor |
invalid-geometry | Non-finite or invalid dimensions/coordinates | Validate numeric input and respect local/world units |
resource-limit | Codec/format budget exceeded | Reduce the candidate or choose a supported bounded scope; record count alone is insufficient |
busy | Active editing preview or controlled proposal | Finish/cancel/resolve that lane before starting another conflicting operation |
stale-revision / stale | Model or owner changed during preparation | Refresh the active snapshot and prepare a new request |
ownership-mode | Operation does not match managed/controlled ownership | Use the matching proposal/acknowledgement path |
history-unavailable | No history entry or current policy blocks replay | Inspect canUndo/canRedo and session history availability |
disposed | Owner was torn down | Bind the operation to the current owner; never reuse a disposed store/controller |
DiagramDiagnostic uses a JSON Pointer path. Store diagnostics add operation
codes. Format/export diagnostics have their own severity, fidelity and location
fields; do not treat every code as the same enum. Use the exact result union
in the API.
#Policy, geometry and input
An unavailable command can be blocked by read-only policy, record/ancestor/layer
locks, action constraints or semantic validation. Inspect availability()/
command state() and show the first useful reason. Current policy is rechecked
when executing, accepting an import or replaying history. Direct host store
writes have separate application authority.
If nested content moves unexpectedly, check parent-local coordinates and the full transform rather than copying world bounds into a local record. Measured content is runtime geometry; invalidate approved measurements after meaningful font/asset changes. Fixed versus dynamic ports use different units. A visual frame is not a structural container or connection endpoint.
If graph shortcuts affect a form, retain native controls or mark the custom
interactive region with [data-diagram-interactive]. Allow composition events
to finish. If an edited value disappears after remount, distinguish unsaved
local drafts from committed Diagram.Field/action data. If graph focus differs
from selection, use the documented selection mode rather than assuming they
are the same state. See Keyboard and input.
#Async operations and output
| Symptom | Recovery |
|---|---|
| Candidate preview visible, current store unchanged | Preview is detached; explicitly accept and resolve any approval and controlled-store proposal |
| Import replaced the page set | Keep the root page ID valid and recreate page/session-bound controllers after ownership changes |
| Late file/provider completion | Observe abort/ticket ownership; ignore superseded results and release callbacks |
| Save resolved but model is still dirty | The acknowledgement covers its captured checkpoint; later edits remain unsaved |
| Output misses custom HTML | Select the rendered viewport with source; detached calls require portable adapters |
| Rooted output has no unique source | Mount one directly owned viewport or bind source explicitly |
| Export color scheme fails | Check required CSS/provider conditions and resources; application bindings retain captured values |
| Transparent JPEG fails | Supply an opaque background or use PNG |
| Large raster plan rejects | Review dimensions/pixel/memory/tile limits; use bounded tile consumption where appropriate |
| Print is prepared but no print dialog | Invoke the browser print action after readiness; preparation is separate from printing |
| Worker falls back or fails | Check deployed worker URL/CSP, fresh dedicated worker factory, transport version and timeout/fallback result |
| Export includes fidelity warnings | Review approximation/loss before sharing; success is not universal format fidelity |
Use the operation's cancel()/dispose() and owned unsubscribe functions on
replacement/teardown. Revoke direct-output object URLs and close prepared print
models. See SSR and lifecycle.
For timing, mount and resource concerns, record the model, browser, viewport and steps that reproduce the issue. Use the performance reference to choose the workload and view settings to investigate.