Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 39 ยท Testing and Performance

Debugging and Developer Tools

Debug SolidJS apps. Trace signal reads and writes, fix lost reactivity, log stores correctly, understand common warnings and hydration mismatches, and use Solid DevTools.

Solid bugs have a different flavor from bugs in virtual-DOM libraries. Components do not re-render, so "why did this re-render?" becomes "why did this not update?" or "what ran when I changed that signal?" Almost every Solid bug falls into a handful of families, and this lesson teaches you to recognize them quickly and gives you tools to trace reactivity.

Bug family 1: reactivity was lost

Reactive reads only track when they happen inside a tracking scope: a JSX expression, createEffect, createMemo, or any function you hand to Solid. Reading outside one gives you a value that never updates.

The three classic mistakes:

  1. Destructuring props: ({ name }) reads props.name once, at setup.
  2. Reading a signal at the top of a component and using the result: const label = count() + " items"; runs once.
  3. Forgetting the call: in JSX works for signals (it passes the function) but count + 1 adds a function to a number.
Lost reactivity side by side

Type in the box: only the "Good" and "Live" lines change. (With JSX plus the Solid compiler, writing <Bad name={name()} /> gives a getter-based props.name, so passing a signal call is fine and destructuring inside the component is the bug. This html example passes a plain value to Bad to show the same freezing effect without a compiler.)

How to spot it: a value renders correctly once and never changes. The fixes are always the same: read signals and props inside functions, JSX, memos or effects. Solid's ESLint plugin (eslint-plugin-solid) flags these patterns at edit time and is worth adding to every project. Use splitProps and mergeProps to separate or default props without breaking reactivity.

Bug family 2: an effect runs too often, too rarely, or in a loop

Effects re-run when any signal they read changes. To find out which ones, trace reads by wrapping the signal:

A tiny signal tracer

The log shows exactly which write woke the effect and in which order the reads happen. Writing the same value again causes no effect run, because signals compare with === before notifying. If an effect writes to a signal that it also reads, you get an infinite loop; fix it by reading with untrack, by moving the write to a different effect, or by using on with explicit dependencies (performance).

Bug family 3: logging stores and proxies

console.log(store) prints a Proxy, which is hard to read and, in browser consoles, may show stale values when expanded later. Print a snapshot instead:

JavaScript
import { unwrap } from "solid-js/store";

console.log(JSON.parse(JSON.stringify(store)));   // a plain deep copy, safe and readable
console.log(structuredClone(unwrap(store)));      // same idea, keeps Dates and Maps

Also remember that console.log(store.items) reads items but not the properties inside it; inside an effect it does not track them. To log reactively, read everything: createEffect(() => console.log(JSON.stringify(store))) re-runs on any change anywhere in the store, which is also a quick way to see what changed when.

Bug family 4: warnings in the console

Message (shortened) Meaning Fix
computations created outside a createRoot An effect or memo was created with no owner, so it will never be cleaned up Create it inside a component or wrap it in createRoot
cleanups created outside a createRoot onCleanup called with no owner Call it during component setup or inside an effect
Cannot read properties of undefined A resource or optional value is not ready Guard with Show, optional chaining or initialValue
Cannot update a store directly You mutated a store (store.x = 1) Use setStore (stores)
Hydration mismatch Server HTML differs from the first browser render See below

Solid prints these only in the development build. Production builds drop the checks, so always develop with the dev build.

Bug family 5: hydration mismatches (SolidStart)

With server rendering, the browser must render exactly what the server sent. Common causes of a mismatch:

  • Time and randomness in render: new Date(), Math.random(), crypto.randomUUID() during render give different values on server and client. Compute them in onMount, or pass them in from the server.
  • Browser-only APIs such as window.innerWidth or localStorage read during render. Defer to onMount or use isServer from solid-js/web.
  • Invalid HTML (a <div> inside a <p>): the browser parser repairs the HTML, so the DOM no longer matches what Solid expected.
  • Differences in locale or time zone: formatting a date with toLocaleString() can differ between server and browser.

The fix pattern for client-only values:

TSX
const [width, setWidth] = createSignal(0);          // same on server and first client render
onMount(() => setWidth(window.innerWidth));         // runs only in the browser, after hydration

Solid DevTools

The Solid DevTools browser extension (Chrome and Firefox) with the solid-devtools package gives you:

  • a component tree showing the props, signals, memos and stores of each component,
  • the owner and dependency graph: which computations depend on which signals,
  • inspect and locate: click an element on the page to jump to the component, or from a component to its source file,
  • a structure view and signal updates highlighted live.

You add it in development only:

TypeScript
// src/index.tsx
import "solid-devtools";                 // after installing solid-devtools and the extension

Or use the Vite plugin from solid-devtools/vite. Because Solid does not re-render, the tool highlights which signal changed and which computations ran, which answers the "what ran" question directly.

Other practical tools

  • Source maps and the Sources panel: breakpoints inside event handlers and effects work as usual; the stack of an effect shows the signal write that caused it.
  • createEffect(() => console.log(...)) as a live watch window for any expression.
  • The Performance panel to find long tasks, and counters like those in the performance lesson.
  • getOwner() during setup to see the owner chain when a context or cleanup is missing: useContext returning undefined almost always means the component is outside the provider (context).
  • ESLint with eslint-plugin-solid to catch lost reactivity before running the code.

A debugging checklist

  1. Does the value render but never update? Look for destructured props or a read outside a tracking scope.
  2. Does an effect run too often? Trace what it reads; use on or untrack.
  3. Does a store log odd values? Log a snapshot.
  4. Is there a warning? Read the table above; it is nearly always about ownership.
  5. Server-rendered page flashes or warns about hydration? Look for time, randomness and browser-only reads in render.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A value renders correctly once and never updates. What is the most likely cause?

    Tracking only happens inside reactive scopes, so a value read at setup is a frozen snapshot.
  2. 2. How do you print a readable copy of a store?

    A deep copy avoids the Proxy and shows the current values at the moment of logging.
  3. 3. Where should code reading window.innerWidth run in a server-rendered Solid app?

    onMount runs only in the browser after hydration, so the server and first client render agree.
  4. 4. What does the warning about computations created outside a createRoot mean?

    Computations need an owner for automatic cleanup; create them inside a component or a root.

Summary

  • Most Solid bugs are lost reactivity: read signals and props inside functions, JSX, memos or effects.
  • Trace reads and writes with a wrapper or an effect that logs; same-value writes do not notify.
  • Log store snapshots, and read everything inside an effect to watch the whole store.
  • Warnings are dev-only and mostly about ownership; hydration mismatches come from time, randomness and browser-only reads.
  • Use Solid DevTools and eslint-plugin-solid for the component tree, dependency graph and early warnings.

Next: Project: A Todo App with Stores and Filters