Troubleshooting

Common issues and how to fix them. Every problem here has a known cause.

Setup & Installation

Check that LayProvider wraps your app and has a valid projectId. The project must be marked "active" in the dashboard (or pass the active prop). Also verify that the project exists — an incorrect projectId will cause the widget to silently not render.

How do I install Lay in a Vite or CRA project?

Install the SDK with npm install @uselay/sdk, then wrap your root component in LayProvider with your projectId. Lay works with any React 18+ project — there is no framework-specific setup. Vite, CRA, Remix, and plain React all work the same way.

tsx

import { LayProvider } from '@uselay/sdk';

function App() {
  return (
    <LayProvider projectId="your-project-id">
      <YourApp />
    </LayProvider>
  );
}

identifyUser throws "LAY_SECRET_KEY not set"

identifyUser reads process.env.LAY_SECRET_KEY at runtime. Two things to check: (1) Add LAY_SECRET_KEY=sk_... to your .env file — never prefix it with NEXT_PUBLIC_. (2) Make sure identifyUser is called server-side in your layout, not in a client component.

tsx

import { identifyUser } from '@uselay/sdk/server';
import { LayProvider } from '@uselay/sdk';

export default async function Layout({ children }: { children: React.ReactNode }) {
  const user = await getUser();
  return (
    <LayProvider
      projectId="your-project-id"
      {...identifyUser(
        user ? { id: user.id, name: user.email ?? user.name } : null
      )}
    >
      {children}
    </LayProvider>
  );
}

Comments not visible to other team members

Comments are scoped to a project. Make sure all team members are accessing the same projectId and that the project is shared in your dashboard workspace. If you are using Support mode, comments from anonymous users will only appear in the dashboard — not in the widget for other visitors.

Does Lay work with SSR or server components?

Yes. LayProvider is a client component — its published build includes the "use client" directive. Next.js handles the boundary automatically, so you can render it directly in a server layout without a wrapper file.

tsx

import { LayProvider } from '@uselay/sdk';

export default async function Layout({ children }: { children: React.ReactNode }) {
  return (
    <LayProvider projectId="your-project-id">
      {children}
    </LayProvider>
  );
}

Comments & Anchoring

Comments disappear after a deploy

Comments are anchored to DOM elements via CSS selectors. If your selectors changed (class names, IDs, structure), the SDK attempts fingerprint-based recovery. If that fails, comments appear in the Detached Comments panel. Add data-feedback-id attributes to critical elements to prevent this.

tsx

<button data-feedback-id="checkout-submit">Place Order</button>

Comments show on the wrong element

This usually happens when multiple similar elements share the same generated selector (e.g., list items without unique attributes). Add data-feedback-id to distinguish them, or use unique id attributes. The SDK selector algorithm prioritizes these stable attributes over positional selectors.

How do I remove or delete a comment?

Open the comment in the dashboard and click the delete option in the comment menu. Deleted comments are removed from both the dashboard and the widget. Only the comment author or a project admin can delete comments. There is no bulk delete — this is intentional to prevent accidental data loss.

AI Enrichment

AI context cards are not showing

AI enrichment is enabled by default. Verify that the ai prop is not set to false. AI processing takes a few seconds after comment creation — check the dashboard. If the project was created before AI was available, check the project settings in the dashboard.

Can I use Lay without AI enrichment?

Yes. Pass ai={false} to LayProvider to disable AI enrichment entirely. Comments will still be anchored to elements and visible in the dashboard — you just won't see AI context cards, intent detection, or fix suggestions. You can re-enable AI at any time from the dashboard or by removing the prop.

tsx

<LayProvider projectId="your-project-id" ai={false}>
  <YourApp />
</LayProvider>

Linear Integration

Issues aren’t being created in Linear

Check that Linear is connected in Settings (status should show "Connected"). Open the project and verify the Linear toggle is on and a team is selected. New issues are created for root comments only — replies become comments on the existing issue.

Wrong team is receiving issues

Each project has its own team setting. Open the project in the dashboard and change the team in the Linear dropdown.

Status changes in Linear aren’t reflected

Lay uses webhooks to receive status updates. If the webhook was disrupted, disconnect and reconnect Linear in Settings to register a new webhook.

Keyboard shortcut C does not work

The shortcut is disabled when focus is inside an input, textarea, or contenteditable element. Click outside any form field and try again. Also check that no other library is capturing the "c" keydown event before it reaches the Lay listener.

If you pass an object prop like user inline on every render, it creates a new reference each time and the provider re-initializes. Define objects outside the component or use useMemo.

tsx

// Stable reference — defined once outside the component
const user = { id: 'u_123', name: 'Jane' };

function App() {
  return (
    <LayProvider projectId="your-project-id" user={user}>
      <YourApp />
    </LayProvider>
  );
}

How do I switch between Review and Support mode?

Set the mode prop on LayProvider to "review" or "support". You can also change the mode from the project settings in the dashboard without redeploying. The prop takes precedence over the dashboard setting when both are set.

tsx

// Review mode for staging
<LayProvider projectId="..." mode="review">

// Support mode for production
<LayProvider projectId="..." mode="support">

Lay uses CSS custom properties prefixed with --fl- for theming. Override these in your stylesheet to change colors, sizes, and spacing. The widget is rendered in a scoped container that won't leak styles into your app.

The widget uses a high z-index to stay above your app content. If it conflicts with your own overlays (modals, dropdowns), adjust your z-index values or use the Lay dashboard to reposition the toggle button. The default position is bottom-right.