Troubleshooting

Each entry gives the symptom, the cause and what to do. When EVK cannot do something, it shows a visible state instead of failing silently. Start from what the UI or onStatus/onIndexChange reports.

Installation and loading

ERR_PACKAGE_PATH_NOT_EXPORTED or ERR_REQUIRE_ESM. EVK is ESM-only and only the documented subpaths are exported. Use import, and import entity-viz-kit/core (etc.), never entity-viz-kit or a file path inside the package.

“Cannot find module ‘react’” in a core-only app. You imported entity-viz-kit/react or /react/graph. Core, highlighter and graph never load React. Install React 18.3 or 19 only if you use the React entries.

document is not defined during server rendering. Imports are SSR-safe, but calling mountGraph, attachHighlighter or createDomTextMap needs a browser. Call them in an effect or other client-only code.

Unstyled components. Import entity-viz-kit/styles.css once, and render components inside EntityVizProvider: the theme tokens live on its .evk root.

Host page styles leak into EVK (odd fonts, huge buttons, * { all: unset }). EVK rules are class-scoped and do not reset the host page. A very aggressive host reset can still reach EVK elements. Scope your reset away from .evk and .evk-graph, or give those roots a wrapper with more specific rules. EVK uses !important only to honor reduced motion.

Graph

Status says “Layout worker unavailable”. The Worker script did not load: wrong workerUrl, the file not deployed, or a CSP without worker-src for it. Serve entity-viz-kit/graph/worker from your origin (see installation). The graph keeps a static layout, and pins and manual positioning still work.

“Graphics unavailable. Use the entity and relation navigator below.” WebGL2 is missing, blocked or lost. The accessible navigator opens automatically and every action stays available there. Retry graphics re-creates the context after a loss. In headless Linux CI, run under xvfb-run with EVK_GRAPH_SOFTWARE_GL=1 so the tests use SwiftShader. Without a working GL backend, the rendering tests fail rather than pretending to render.

Slow frames on large graphs. The recorded targets are unmet under SwiftShader (ADR 0004 and npm run bench:graph:browser). Lower labelBudget and maxPixelRatio, reduce visible entities with setVisibleEntities, and measure on your real hardware.

Reading, anchors and sources

An evidence quote shows “ambiguous”. The quote occurs more than once and its prefix and suffix do not pick one occurrence. EVK lists the candidates and never guesses. Supply a longer prefix/suffix from your backend.

“unavailable” anchors. The quote no longer occurs in the current source version. Re-extract the anchor against the current text, or serve the version the evidence was made from.

A source says withdrawn, inaccessible or invalid. Your adapter returned that status, or returned data that failed validation (malformed IDs, unsafe URLs, oversize fields). Validation failures are deliberate: EVK treats adapter data as untrusted. The error names the field; fix it at the source.

Results say “Previous results — not answers to the current query”. A newer query is in flight or failed. EVK keeps the last results visible but labeled, instead of showing stale data as current. Retry re-runs the current query.

Live highlighter

Nothing is painted and renderMode: 'native' reports an error. The page’s CSP blocked the injected highlight stylesheet. Use renderMode: 'auto' (overlay fallback), pass styleNonce, or install the CSS yourself with installStyle.

Mentions disappear after the page changes, then return. That is repair: stale ranges are withdrawn at once, and anchors are re-resolved after a short debounce. If onIndexChange reports failed, the next mutation or refresh() retries.

Some annotations are never painted. Their anchors are ambiguous or unavailable in the live text, or they fall inside excluded regions. The default exclusions are scripts, styles, form controls, buttons, frames, editable regions, [hidden], [aria-hidden="true"], [data-evk-private] and [data-evk-exclude], plus your excludeSelector. getMentions() lists unresolved mentions last, each with its anchor status.

Clicks on a highlight also trigger the host’s link or handler. By design, EVK never cancels host events. Activation is additive and bounded; handle it in onActivate.

Extensions

The panel says “EVK has no access to this page”. The extension has standing access only to http://127.0.0.1/*. On any other site, click the toolbar button or press Alt+Shift+E: that one-time grant is the only way in. A page click alone is not a user gesture for the extension.

The panel says “EVK is not active on this tab” after navigation. Each document is its own session. Navigation retires it, and late messages from the old page are dropped. Activate again on the new page.

Firefox leaves highlights on the page after the add-on reloads. Firefox unloads content scripts without running their cleanup. The page stays usable, and reloading it removes the paint. This is recorded in ADR 0007.

Presentation

The audience shows “stale” or “reconnecting”. A reloaded operator is a new session. The audience keeps the last view, labeled stale, until the new session publishes. “Reconnecting” means no heartbeat for about 4 seconds. Both states are safe: the audience never shows unpublished operator state.

The operator cannot publish (“another window took over”). A newer operator session is presenting. Use Take over the audience from here in the window you want.

Nothing crosses between machines. The reference transport is a same-origin BroadcastChannel. Implement PresentationTransport over your own authenticated channel.

Test environments

EVK_BROWSER_EXECUTABLE required. Browser suites need a real Chromium or Chrome. They never silently skip. Point the variable at Chrome for Testing or a system Chromium. suite:firefox needs EVK_FIREFOX_EXECUTABLE (Firefox 128+ with Marionette).

Intermittent net::ERR_NETWORK_CHANGED or a page that never becomes ready. Chromium cancels in-flight loads, even on 127.0.0.1, when the machine’s network interfaces change. During construction, Docker kept creating veth interfaces and caused about 1 failed load in 60. Run on a machine without interface churn, or rerun the suite. The failure is reported as a failure, not retried away.

ERR_BLOCKED_BY_ADMINISTRATOR. A managed browser policy blocks localhost. Use Chrome for Testing, or run the isolated-document route (suite:memory) in addition to, not instead of, the HTTP route.

The ONAB checks refuse to run. They need Python 3.12+. npm run onab:doctor names the missing prerequisite.