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

# Troubleshooting

> Common issues and solutions for Limelight SDK and MCP server setup.

## SDK Issues

<AccordionGroup>
  <Accordion title="No data appearing in the desktop app">
    **Check the connection target.** If you're using the desktop app, make sure you're not setting `target: "mcp"`:

    ```typescript theme={null}
    // For desktop app — don't set target, or omit it
    Limelight.connect();

    // For MCP server
    Limelight.connect({ target: "mcp" });
    ```

    **Check that the app is running.** Limelight streams data in real time — you need to interact with your app to see events.

    **Check the port.** The desktop app listens on port 8347 by default. If you're running something else on that port, there may be a conflict.
  </Accordion>

  <Accordion title="Network requests not showing up">
    Limelight intercepts `fetch` and `XMLHttpRequest`. If your app uses a different HTTP client that doesn't go through these APIs, requests won't be captured.

    **React Native:** Make sure `Limelight.connect()` is called early — before your first network request. If the SDK initializes after requests have already fired, those early requests will be missed.

    **Verify it's enabled:**

    ```typescript theme={null}
    Limelight.connect({
      enableNetworkInspector: true, // default is true
    });
    ```
  </Accordion>

  <Accordion title="Renders not being tracked">
    Render tracking requires React. It works by walking the React Fiber tree, so:

    * Make sure you're using React 16.8+ (hooks support)
    * The SDK must be initialized before your app renders
    * Render tracking is automatic — no wrappers or HOCs needed

    If renders still don't appear, check that you haven't disabled them:

    ```typescript theme={null}
    Limelight.connect({
      enableRenderTracking: true, // default is true
    });
    ```
  </Accordion>

  <Accordion title="State changes not captured">
    State inspection requires you to pass your stores to the SDK:

    ```typescript theme={null}
    Limelight.connect({
      stores: {
        authStore: useAuthStore,
        cartStore: useCartStore,
      },
    });
    ```

    **Zustand:** Pass the hook directly (e.g., `useAuthStore`). For vanilla stores, pass the store object.

    **Redux:** Pass `{ store: yourReduxStore }`.

    Limelight currently supports **Zustand** and **Redux**. Jotai and MobX support is coming soon.
  </Accordion>

  <Accordion title="Physical device not connecting">
    When debugging on a physical device (not a simulator), the device needs to reach your development machine over the network.

    ```typescript theme={null}
    Limelight.connect({
      projectKey: "project-123" // you will need to use the hosted web version of limelight
    });
    ```

    Make sure:

    * Your device and machine are on the same network
    * Port 8347 (desktop app) or 9229 (MCP server) isn't blocked by a firewall
  </Accordion>
</AccordionGroup>

## MCP Server Issues

<AccordionGroup>
  <Accordion title="AI assistant not seeing any data">
    **1. Check that both the MCP server and your app are running.**

    The MCP server needs to be running, and your app needs to be connected with `target: "mcp"`:

    ```typescript theme={null}
    Limelight.connect({ target: "mcp" });
    ```

    **2. Verify the MCP server is receiving events.**

    Run with `--verbose` to see incoming events:

    ```bash theme={null}
    npx limelight-mcp --verbose
    ```

    **3. Check the port.**

    The SDK sends to port 9229 by default. If you changed the MCP server port, update the SDK:

    ```typescript theme={null}
    Limelight.connect({
      target: "mcp",
      serverUrl: "ws://localhost:YOUR_PORT",
    });
    ```
  </Accordion>

  <Accordion title="MCP server not connecting to Cursor">
    Cursor uses a JSON configuration file for MCP servers. Make sure the config is correct:

    ```json theme={null}
    {
      "mcpServers": {
        "limelight": {
          "command": "npx",
          "args": ["limelight-mcp"]
        }
      }
    }
    ```

    **Common issues:**

    * The config file location depends on your Cursor version — check Cursor's MCP documentation
    * `npx` must be available in your PATH
    * Restart Cursor after changing the MCP config
  </Accordion>

  <Accordion title="MCP server not connecting to Claude Code">
    Run this command to add Limelight:

    ```bash theme={null}
    claude mcp add limelight-mcp npx limelight-mcp
    ```

    If the server was added but isn't working:

    * Run `claude mcp list` to verify it's registered
    * Check that `npx` is available in your shell
    * Try running `npx limelight-mcp` directly to see if there are errors
  </Accordion>

  <Accordion title="Port conflict (port 9229 in use)">
    Port 9229 is also used by Node.js's inspector. If you're running `--inspect`, there will be a conflict.

    Use a different port:

    ```bash theme={null}
    npx limelight-mcp --port 9230
    ```

    And update your SDK config:

    ```typescript theme={null}
    Limelight.connect({
      target: "mcp",
      serverUrl: "ws://localhost:9230",
    });
    ```
  </Accordion>

  <Accordion title="Events disappearing or missing old data">
    The MCP server stores events in memory with a default cap of 10,000 events. Once the cap is reached, older events are evicted.

    To increase the limit:

    ```bash theme={null}
    npx limelight-mcp --max-events 50000
    ```

    Data resets when the server restarts — this is by design. The MCP server is a development tool, not a persistence layer.
  </Accordion>
</AccordionGroup>

## Server-Side Issues

<AccordionGroup>
  <Accordion title="Server requests not linking to client requests">
    Full-stack tracing requires both the client SDK and server middleware to be running. The client attaches an `x-limelight-trace-id` header to every outgoing request, and the server middleware reads it.

    **Check that the middleware is installed:**

    ```typescript theme={null}
    // Express
    app.use(limelightMiddleware());

    // Next.js Pages Router
    export default withLimelight(handler);
    ```

    **Make sure the middleware is added before your routes** — otherwise requests won't be captured.

    **Custom trace header:** If your infrastructure strips custom headers, you can configure a different header name:

    ```typescript theme={null}
    Limelight.connect({
      traceHeader: "x-my-trace-id",
    });
    ```
  </Accordion>

  <Accordion title="Next.js App Router not supported">
    The server-side middleware currently supports **Express**, **Connect**, and **Next.js Pages Router**. App Router support is in progress.

    If you're using Next.js App Router, you can still use the client-side SDK for network, render, state, and console capture.
  </Accordion>
</AccordionGroup>

## Still stuck?

* Check the [GitHub Issues](https://github.com/getlimelight/limelight-sdk/issues) for known issues
* Email us at [hello@getlimelight.io](mailto:hello@getlimelight.io)