Skip to main content

​
SDK Issues

Check the connection target. If you’re using the desktop app, make sure you’re not setting target: "mcp":
// 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.
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:
Limelight.connect({
  enableNetworkInspector: true, // default is true
});
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:
Limelight.connect({
  enableRenderTracking: true, // default is true
});
State inspection requires you to pass your stores to the SDK:
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.
When debugging on a physical device (not a simulator), the device needs to reach your development machine over the network.
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

​
MCP Server Issues

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":
Limelight.connect({ target: "mcp" });
2. Verify the MCP server is receiving events.Run with --verbose to see incoming events:
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:
Limelight.connect({
  target: "mcp",
  serverUrl: "ws://localhost:YOUR_PORT",
});
Cursor uses a JSON configuration file for MCP servers. Make sure the config is correct:
{
  "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
Run this command to add Limelight:
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
Port 9229 is also used by Node.js’s inspector. If you’re running --inspect, there will be a conflict.Use a different port:
npx limelight-mcp --port 9230
And update your SDK config:
Limelight.connect({
  target: "mcp",
  serverUrl: "ws://localhost:9230",
});
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:
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.

​
Server-Side Issues

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:
// 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:
Limelight.connect({
  traceHeader: "x-my-trace-id",
});
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.

​
Still stuck?