---
title: Troubleshooting
description: Symptoms and one-step fixes — missing document.modelContext, tools not registering, Next.js transpile errors, and more.
---

Find your symptom, open it, apply the one fix.

<Accordion>
  <AccordionItem title="document.modelContext is undefined">
    WebMCP isn't active in the browser. Chrome 150+: enable the flag in `chrome://flags` for localhost. Chrome 149 exposes only `navigator.modelContext` — the SDK handles it, but your devtools check should look there. See [Browser setup](/installation#browser-setup).
  </AccordionItem>
  <AccordionItem title="Tools don't appear on the page">
    The entry module isn't running. Tool modules are side-effect-free by design — defining a tool registers nothing. Check that the module calling `registerTools` is actually imported on that page, and in a SPA that the registering component is mounted.
  </AccordionItem>
  <AccordionItem title="A tool shows 'failed' in the registration result">
    Almost always a duplicate `name` — another tool with the same wire name is already registered on the page. Rename one. Note that a duplicate *within one batch* fails the entire `registerTools` call instead, with a thrown error.
  </AccordionItem>
  <AccordionItem title="Next.js build error inside the SDK">
    Your repo has a *vendored* (source-exporting) copy of the SDK, and Next.js won't transpile dependencies by default. Add it to `next.config.js`:

    ```js
    transpilePackages: ["@nekuda/webmcp-sdk"],
    ```

    Use the package name your repo's `package.json` actually declares — older workspaces may vendor it under the legacy alias `@nekuda/webmcp` or `@agentlane/webmcp`.
  </AccordionItem>
  <AccordionItem title="TypeScript error on execute's input type">
    The input shape must be declared as a `type`, not an `interface` — interfaces have no implicit index signature and fail the SDK's generic constraint.
  </AccordionItem>
  <AccordionItem title="Plugin installed but the skills are missing">
    Check the version — the plugin needs Claude Code 2.1.220+ (`claude --version`). Then refresh:

    ```
    /plugin marketplace update
    ```

    and confirm with `claude plugin details webmcp-kit@nekuda` — expect `Skills (2): implement, verify`.
  </AccordionItem>
  <AccordionItem title="The plan proposed fewer tools than I expected">
    That's usually the plugin being honest, not lazy. Journeys with no safe client-reachable path are listed as *needs developer wiring* instead of being wrapped in fake data, and thin-content sites get a single `ask_site` tool rather than padding. The plan tells you which journeys were held back and why — wiring them is your call.
  </AccordionItem>
  <AccordionItem title="Verification reported 'could-not-verify'">
    The tool is plausible but unproven — usually no browser was available, or there was no safe way to invoke a state-changing tool. It ships flagged. Re-check it anytime with [`/webmcp-kit:verify`](/skills/verify) against a local run with seeded data.
  </AccordionItem>
</Accordion>