> ## Documentation Index
> Fetch the complete documentation index at: https://knitkit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```ts theme={null}
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
  }
}
```

<Note>
  `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.
</Note>

***

## Error code reference

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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>`.
</Accordion>

<Accordion title="KNIT_ERR_SRI_MISMATCH">
  <Note>
    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.
  </Note>

  **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.
</Accordion>