solid-errors-reactivity-debugging

name	solid-errors-reactivity-debugging
description	Use when SolidJS reactivity is broken, effects are not firing, or store updates are not reflected in the UI. Prevents lost tracking from destructuring, conditional signal access, async tracking loss, and stale closures. Covers diagnostic flowcharts, solid-devtools debugging, effect tracking issues, store propagation failures, and systematic symptom-to-fix resolution. Keywords: reactivity debugging, effect not firing, store not updating, signal tracking, solid-devtools, stale closure, createEffect.
license	MIT
compatibility	Designed for Claude Code. Requires SolidJS 1.x/2.x with TypeScript.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

solid-errors-reactivity-debugging

Quick Reference

Diagnostic Table: Symptom to Cause to Fix

Symptom	Cause	Fix
UI never updates after signal change	Signal getter not called in JSX: {count} instead of {count()}	ALWAYS call the getter: {count()}
Effect runs once, never again	Signal accessed outside tracking scope (component body, event handler)	Move signal access inside createEffect or JSX expression
Effect ignores some signals	Conditional access / early return before signal read	Read ALL signals before any conditional logic
Store property not updating in UI	Destructured store property: const { name } = store	ALWAYS access via store.name in JSX
Store update has no effect	Direct mutation: store.name = "x"	ALWAYS use setStore("name", "x")
Props stop updating	Destructured props: function Comp({ name })	ALWAYS use props.name, use splitProps if needed
Value is stale in timeout/callback	Signal value captured: const v = count() then used later	Call count() at the point where you need the value
Effect works initially but stops	await inside effect breaks synchronous tracking	Move async code to a separate function; read signals before await
Memo returns stale value	Memo dependency was untracked or destructured	Verify all signal getters are called inside memo callback
Store array update not reflected	Used store.items.push() instead of setter	Use setStore("items", items.length, newItem) or produce

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

Scope	Tracks Dependencies	Re-runs
createEffect(() => ...)	YES	When dependencies change
createMemo(() => ...)	YES	When dependencies change
createRenderEffect(() => ...)	YES	When dependencies change (sync)
createComputed(() => ...)	YES	When dependencies change (before render)
JSX expressions {count()}	YES	When dependencies change

What is NOT a Tracking Scope

Context	Tracks	Why
Component function body	NO	Runs exactly once during setup
Event handlers onClick={() => ...}	NO	Run on demand, not reactively
onMount(() => ...)	NO	Explicitly non-tracking, runs once
setTimeout/setInterval callbacks	NO	Scheduled by the browser, not SolidJS
untrack(() => ...)	NO	Deliberately suppresses tracking
Code after await	NO	Async breaks synchronous tracking context

---

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.

// WRONG — signals after await are NOT tracked
createEffect(async () => {
  const response = await fetch("/api/data");
  console.log(count()); // NOT tracked — effect will NOT re-run when count changes
});

// CORRECT — read all signals BEFORE await
createEffect(() => {
  const currentCount = count(); // Tracked
  const url = apiUrl();         // Tracked

  // Non-tracked async work in a separate scope
  (async () => {
    const response = await fetch(url);
    const data = await response.json();
    setResult(data);
  })();
});

---

SolidJS 2.x Debugging Differences

Aspect	1.x Behavior	2.x Behavior
Update timing	Synchronous propagation	Microtask-batched — reads stale until flush
Debugging reads	Values update immediately after set	Values may appear stale until batch flushes
Immediate propagation	Default behavior	Use flush() when needed
Dev warnings	Manual detection only	Built-in warnings for accidental top-level reads
Effect model	Single createEffect	Split compute/apply — inspect each phase separately

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:

// Step 1: Verify the signal itself updates
createEffect(() => {
  console.log("[DEBUG] count =", count());
});

// Step 2: If this fires but your UI does not, the problem is in HOW the signal
// is accessed in your component (destructuring, conditional, async)

Strategy 2: Tracking Scope Verification

Wrap suspect code in createEffect to confirm tracking works:

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

Strategy 3: solid-devtools

Install solid-devtools for visual dependency graph inspection:

npm install --save-dev solid-devtools

// vite.config.ts
import devtools from "solid-devtools/vite";

export default defineConfig({
  plugins: [devtools(), solidPlugin()],
});

// Entry point (index.tsx / App.tsx)
import "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