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.
typescript1// 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
| 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:
typescript1// 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:
typescript1// 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:
bash1npm install --save-dev solid-devtools
typescript1// vite.config.ts 2import devtools from "solid-devtools/vite"; 3 4export default defineConfig({ 5 plugins: [devtools(), solidPlugin()], 6});
typescript1// 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
