Troubleshooting

Start with diagnostics, then decide whether the problem is source, rendering, integration, or delivery. Changing layout settings cannot fix an invalid model, and changing theme tokens cannot fix an SVG loaded in the wrong way.

The diagram does not render

Run the checker against the smallest failing file:

pnpm kdiagrams check path/to/diagram.kdiagram

In JavaScript, inspect result.diagnostics even when renderToSvg resolves. Source errors are reported as data rather than thrown exceptions.

Common causes are an undeclared node ID, an unclosed quote or block, a misspelled property, or an edge that references a table column that does not exist.

Vite says a Node module was externalized

If you see an error mentioning node:module, node:fs, or createRequire in client code, make sure your browser imports come from documented public package entry points:

example.ts

import { KDiagram } from "@kekonic/diagrams";
import "@kekonic/diagrams-element";

Do not import source files, dist internals, CLI code, or Node-only helpers into a client component. Update all @kekonic/diagrams* packages together so the facade and lower-level packages stay on one release. Delete a stale bundler dependency cache after upgrading if it still resolves an older build.

For static sites, prefer server-side renderToSvg or the CLI. Mark the rendering module as server-only so the framework does not include it in a client island accidentally.

Browser and CLI output differ

Kekonic Diagrams uses font measurement during layout. Wait for element.ready() in a browser before taking a screenshot. In custom browser rendering paths, call await KDiagram.ensureFonts() before the first render when font timing matters.

Node emits diagnostic FM210 if the bundled measurement font cannot be loaded and approximation is used. Verify package installation and avoid comparing output produced by mismatched package versions.

An icon is missing

Bare icons use the default collection; brand icons usually need a prefix such as simple-icons:stripe or logos:postgresql. Browsers fetch requested icons, so check CSP, network access, and the configured API base URL. Offline applications should register a local collection.

The layout is technically correct but hard to read

Do not begin with spacing. Try this order:

1. State the question the diagram answers.
2. Remove nodes and edges that do not answer it.
3. Make the main path and reading direction explicit.
4. Add meaningful boundaries.
5. Shorten labels.
6. Apply density, arrangement, or crossing controls.
7. Split the view.

See Control layout for symptom-specific advice.

The SVG has the wrong colors elsewhere

External images do not inherit CSS variables from the page that contains them. CLI renders snapshot colors by default; use snapshotTheme: true with the JavaScript SDK. Inline --live-theme or other non-snapshotted SVG only when the host deliberately provides Kekonic Diagrams theme variables.

If theme="auto" does not follow your app, ensure the current mode is written to document.documentElement.dataset.theme.

The live diagram has no height

Give <k-diagram> or KDiagramLive an explicit height. Percentage heights only work when the containing block also has a resolved height.

Reduce a bug before reporting it

Keep the smallest source that still fails, record the @kekonic/diagrams* package versions, state whether the failure occurs in Node or a browser, and include diagnostics. For layout issues, include both source and SVG; a screenshot alone hides the graph the engine received.