solid-errors-reactivity-debugging

Quick Reference

Diagnostic Table: Symptom to Cause to Fix

Critical Warnings

NEVER destructure props in the function signature — this reads values once and permanently breaks tracking. ALWAYS accept props as a single object and access properties reactively.

NEVER store a signal getter result in a variable and expect it to stay current — const v = count() captures a snapshot. ALWAYS call the getter where you need the live value.

NEVER place await before signal reads in an effect — await breaks the synchronous tracking scope. ALWAYS read all tracked signals before any await.

NEVER mutate a store directly — store.x = 5 bypasses the reactive system entirely. ALWAYS use setStore or produce.

NEVER use Array.push/splice/pop on store arrays — these mutate without notifying the reactive graph. ALWAYS use setStore with path syntax or produce.

Diagnostic Flowchart: "My UI Is Not Updating"

START: UI is not updating after state change
  |
  +--> Is the value a signal?
  |     |
  |     +--> Are you calling the getter? count() not count
  |     |     |
  |     |     +--> NO --> FIX: Add () to signal reads in JSX
  |     |     +--> YES --> Is the signal read inside a tracking scope?
  |     |                   |
  |     |                   +--> NO (component body, event handler, onMount)
  |     |                   |     --> FIX: Move read into createEffect or JSX expression
  |     |                   |
  |     |                   +--> YES --> Is there an early return or condition BEFORE the read?
  |     |                         |
  |     |                         +--> YES --> FIX: Read all signals before conditionals
  |     |                         +--> NO --> Is there an await before the read?
  |     |                               |
  |     |                               +--> YES --> FIX: Read signals before await
  |     |                               +--> NO --> Check equality: signal uses === by default
  |     |                                     --> FIX: Use { equals: false } for objects
  |
  +--> Is the value from a store?
  |     |
  |     +--> Did you destructure the store? const { x } = store
  |     |     --> FIX: Access as store.x in JSX
  |     |
  |     +--> Did you mutate directly? store.x = 5
  |     |     --> FIX: Use setStore("x", 5)
  |     |
  |     +--> Did you use Array.push/splice?
  |     |     --> FIX: Use setStore or produce
  |     |
  |     +--> Did you use setStore correctly?
  |           --> Verify path syntax: setStore("path", "to", "prop", value)
  |
  +--> Is the value from props?
        |
        +--> Did you destructure props? function Comp({ name })
        |     --> FIX: Use function Comp(props) and access props.name
        |
        +--> Did you spread props? <Child {...props} />
              --> FIX: Use splitProps/mergeProps for reactive forwarding

Tracking Scope Rules

What IS a Tracking Scope

What is NOT a Tracking Scope

Async Tracking Loss

The SolidJS reactive system tracks dependencies synchronously. Any signal read after an await is NOT tracked because the execution resumes in a new microtask outside the original tracking scope.

typescript
1// WRONG — signals after await are NOT tracked
2createEffect(async () => {
3  const response = await fetch("/api/data");
4  console.log(count()); // NOT tracked — effect will NOT re-run when count changes
5});
6
7// CORRECT — read all signals BEFORE await
8createEffect(() => {
9  const currentCount = count(); // Tracked
10  const url = apiUrl();         // Tracked
11
12  // Non-tracked async work in a separate scope
13  (async () => {
14    const response = await fetch(url);
15    const data = await response.json();
16    setResult(data);
17  })();
18});

SolidJS 2.x Debugging Differences

When debugging 2.x: if a value appears stale immediately after setSignal(), this is expected microtask batching behavior. The value updates after the current synchronous execution completes. Use flush() only when you explicitly need immediate propagation.

Debugging Strategies

Strategy 1: Isolation Effect

Create a minimal effect that ONLY reads the suspect signal to verify it fires:

typescript
1// Step 1: Verify the signal itself updates
2createEffect(() => {
3  console.log("[DEBUG] count =", count());
4});
5
6// Step 2: If this fires but your UI does not, the problem is in HOW the signal
7// is accessed in your component (destructuring, conditional, async)

Strategy 2: Tracking Scope Verification

Wrap suspect code in createEffect to confirm tracking works:

typescript
1// If this logs on changes, tracking works — the bug is elsewhere
2createEffect(() => {
3  console.log("[DEBUG] store.user.name =", store.user.name);
4});

Strategy 3: solid-devtools

Install solid-devtools for visual dependency graph inspection:

bash
1npm install --save-dev solid-devtools

typescript
1// vite.config.ts
2import devtools from "solid-devtools/vite";
3
4export default defineConfig({
5  plugins: [devtools(), solidPlugin()],
6});

typescript
1// Entry point (index.tsx / App.tsx)
2import "solid-devtools";

The devtools browser extension shows: signal values, dependency graphs, component tree, and which computations re-run on each update.

Reference Links

• references/methods.md -- Debugging tools: solid-devtools setup, console.log strategies, tracking scope identification techniques
• references/examples.md -- Complete debugging scenarios with step-by-step diagnosis and fixes
• references/anti-patterns.md -- Debugging mistakes that make problems worse

Official Sources

• https://docs.solidjs.com/concepts/intro-to-reactivity
• https://docs.solidjs.com/concepts/effects
• https://docs.solidjs.com/concepts/stores
• https://github.com/thetarnav/solid-devtools