knitkit Error Codes: FedkitError Reference and Fixes

All knitkit error codes with their meaning, common causes, and suggested fixes — thrown as FedkitError instances with a machine-readable code property.

Every runtime error thrown by @knitkit/runtime is an instance of FedkitError — a subclass of Error that carries three properties: a machine-readable code string drawn from the FedkitErrorCode union, a human-readable message, and an optional suggestion string with a concrete remediation hint. This structure lets you handle federation failures programmatically without parsing error text. The six codes in FedkitErrorCode are all thrown by @knitkit/runtime itself. One additional code — KNIT_ERR_SRI_MISMATCH — is thrown exclusively by @knitkit/node during server-side integrity verification; it is documented at the bottom of this page for completeness.

Catching and inspecting errors

Use the isFedkitError type guard exported from @knitkit/runtime to narrow an unknown thrown value before reading its code:

import { isFedkitError, registerRemotes, loadRemote } from "@knitkit/runtime";

try {
  await registerRemotes([
    { name: "checkout", manifest: "/federation/knit.manifest.json" },
  ]);
  const mount = await loadRemote("checkout/CartWidget");
  mount(document.getElementById("slot"));
} catch (e) {
  if (isFedkitError(e)) {
    console.error(e.code, e.message);
    if (e.suggestion) console.error("Suggestion:", e.suggestion);
  } else {
    throw e; // re-throw anything that isn't a FedkitError
  }
}

isFedkitError is a proper instanceof check against the FedkitError class, so it works correctly across module realms as long as both sides share the same @knitkit/runtime instance — which the import map guarantees.

---

Error code reference

KNIT_ERR_LOAD_FAILED

Thrown when: a network request to fetch a manifest JSON or to dynamically import a remote module fails.

Common causes:

• The manifest URL is wrong, mis-typed, or the CDN path has changed.
• The remote’s server does not send permissive CORS headers (Access-Control-Allow-Origin). The browser will block the fetch and the import silently before knitkit even sees the response.
• The remote server is down or behind a VPN the client can’t reach.
• A relative path passed to registerRemotes resolves to the wrong origin in production.

Fixes:

1. Open the browser Network tab, find the failing request, and confirm the status code and CORS headers.
2. Ensure the remote’s static file host sets Access-Control-Allow-Origin: * (or the specific host origin) on all files under the federation output directory.
3. In Node SSR, check that the manifest URL is reachable from the server’s network, not just the browser’s.

KNIT_ERR_NOT_REGISTERED

Thrown when: you call loadRemote("checkout/CartWidget") but a remote named "checkout" was never passed to registerRemotes.

Common causes:

• loadRemote is called before await registerRemotes(...) has resolved.
• The remote name in loadRemote has a typo — it must match the name field in knit.config.json exactly.
• In a multi-page app, registerRemotes was only called on one route but loadRemote is invoked on another.

Fix: always await registerRemotes([...]) with all the remotes your application needs before calling any loadRemote. If you load remotes lazily on demand, call registerRemotes again with the new remote’s descriptor before loading it — successive calls merge into the existing registry.

KNIT_ERR_MANIFEST_INVALID

Thrown when: the JSON returned by a manifest URL is present but does not conform to the knitkit manifest spec.

Required top-level fields: spec (string), name (string), exposes (object), shared (object). If any of these are missing, have the wrong type, or the spec value is unrecognised, this error is thrown during registerRemotes.

Common causes:

• The manifest was hand-written and a required field was omitted.
• A CDN edge cache is serving a stale or truncated response.
• The wrong URL was given — for example a directory listing or an HTML 404 page instead of JSON.
• The remote was built with an older knitkit version that emitted a different spec value.

Fix: fetch the manifest URL directly in your browser and inspect the JSON. Regenerate it with knitkit build to ensure it matches the current spec. Check for CDN cache-control headers if you see stale data.

KNIT_ERR_NEGOTIATION_CONFLICT

Status: this code is defined in the FedkitErrorCode union but is not thrown by the current runtime. It is reserved for a future multi-phase conflict-detection pass.

If you catch an error with this code today it originates from a future or experimental build of @knitkit/runtime. In the current release, version-range conflicts that involve a singleton: true package surface as KNIT_ERR_SINGLETON_CONFLICT; non-singleton conflicts are resolved silently via import-map scopes entries with no error thrown.

KNIT_ERR_SINGLETON_CONFLICT

Thrown when: two participants (the host and/or multiple remotes) both declare a package as a singleton but their installed versions differ in a way that means they cannot share the same instance.

Why singletons matter: packages like react, react-dom, and global state stores must exist as exactly one instance in memory. knitkit’s import-map approach makes singletons correct by construction for matching versions, but this error fires as a safety guard when versions diverge and sharing would produce a broken runtime state.

Fix: ensure every participant (host and all remotes) that declares a package as singleton installs the same version. Align versions in your monorepo’s root package.json or use a lockfile-sync tool to prevent version drift across separately deployed remotes.

KNIT_ERR_IMPORT_MAP_INJECTION_FAILED

Thrown when: injectImportMap is called in a non-browser environment where document is not defined (for example, Node.js or an edge runtime).

Common causes:

• registerRemotes (which calls injectImportMap internally) was executed in a server-side rendering context without a DOM.
• A bundler or test runner set up a Node environment but did not provide a document global.

Fix: use @knitkit/node for server-side rendering — it handles import-map serialization without requiring a DOM. If you need to run negotiateShared on the server to obtain the import map payload, call it directly and serialize the result to HTML yourself rather than relying on injectImportMap.

In the browser, injectImportMap can also fail if a Content Security Policy (script-src directive) blocks inline <script> injection. Add the appropriate CSP hash or 'unsafe-inline' exception for your import-map <script>.

KNIT_ERR_SRI_MISMATCH

This error code is thrown by @knitkit/node, not by @knitkit/runtime. It will not appear in browser applications. Include this package only in your Node.js SSR setup.

Thrown when (Node SSR only, @knitkit/node): the bytes fetched for a remote module do not match the integrity (SRI sha384) hash recorded in the manifest.

Why this matters: @knitkit/node verifies SRI hashes before executing any remote code on the server, preventing a compromised CDN or cache-poisoning attack from running arbitrary code in your Node process.

Common causes:

• The remote was rebuilt and the manifest was updated, but the old manifest URL is still cached by the host.
• The CDN mutated the file after the manifest was generated (e.g. minification pass added post-build).
• The manifest integrity field was manually edited.

Fix: redeploy the host with the updated manifest URL, or add a cache-busting query parameter to the manifest URL. Always regenerate the manifest with knitkit build after any change to shared or exposed files — never edit SRI hashes by hand.