Debugging Charts

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

symptom

What you see go wrong: a console error, a blank box, a blurry line, a number that differs from the data.

reproduce

Make the problem happen on demand, with the smallest input that shows it.

hypothesis

A guess written as one sentence you can test: "the height is NaN because the value is the text n/a".

NaN

"Not a Number": what arithmetic gives for something like +"n/a" or undefined * 2. It spreads through every calculation it touches.

empty selection

A D3 selection that matched no element. Calls on it do nothing and raise no error.

backing store

The grid of pixels a canvas really holds, set by its width and height attributes.

device pixel ratio

How many physical screen pixels sit behind one CSS pixel (1, 2 or 3 on most screens).

1. 1

   Fix both NaN causes

   In the first example, change the data line to const data = rows.map((r) => ({ day: r.day, rides: +(r.rides ?? r.ride) })).filter((d) => Number.isFinite(d.rides));. The Console prints rects with NaN: 0 of 4 and max of rides: 3992: the misspelled column is read, and the row with n/a is left out. A chart that drops a row should also say so on the page (Topic 4.4).

2. 2

   Fix the blank SVG without guessing

   In the second example, give #a width="600" height="300" in the HTML. diagnose now prints svg 600x300, marks 1, visible 1: the mark was inside the box all along and the missing size was the only problem.

3. 3

   Read a path error and a viewBox error

   The same hunt works for lines. Draw d3.line() through three points where the middle value is undefined: the Console prints Error: <path> attribute d: Expected number, "M0,32L100,NaNL200,0". The text of the error is the path itself, so the NaN tells you which point broke. Add .defined((p) => Number.isFinite(p.v)) to the line and the error goes (the line then splits into pieces: Topic 7.1). A negative height in a viewBox, such as viewBox="0 0 200 -80", prints Error: <svg> attribute viewBox: A negative value is not valid. ("0 0 200 -80").

4. 4

   Check a winter day in a summer zone

   In the third example, change the trip to 2025-06-15T00:30:00Z. Both days print 2025-06-15, because Azores summer time is UTC+0. A time-zone bug can hide for half a year, so test one winter and one summer date.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: a chart gives little feedback. A wrong number draws a wrong bar and says nothing. A typo in a selector draws nothing and says nothing. Without a method people change five things at once, and the bug disappears for reasons they do not understand. A method makes the search short and the lesson stick.

2. 2

   The method has five steps. Reproduce: make it fail every time, with the smallest data that shows it. Shrink: remove everything not needed until the bug is tiny. Observe: look at facts, not feelings (the console, the element in the inspector, a logged value). Guess: write one sentence, "I think X because Y". Change one thing and run again. If the guess was wrong, you still learned something. Never change two things between runs.

3. 3

   The NaN hunt. A bad value makes an SVG attribute invalid, and Chromium prints a real message: Error: <rect> attribute height: Expected length, "NaN". The message names the element and the attribute but not the datum. Work backwards: select the elements whose attributes contain NaN, read the datum bound to each (d3.select(node).datum()), and compare it with the raw input. The first example finds two causes in one run: the text n/a and a misspelled column name. Both become NaN, and JSON.stringify hides it by printing null.

4. 4

   The blank SVG has three usual causes, checked in this order. One: no size, so the SVG is 300 by 150 pixels and the marks sit outside. Two: the selection is empty (a typo in the id, or the script ran before the element existed), so every later call quietly does nothing. Three: the marks exist but sit outside the visible box, usually an unflipped y scale or a wrong margin. A small diagnose function that prints the SVG's size, the mark count and how many marks are visible answers all three in one look.

5. 5

   The blurry canvas is a size mismatch. A canvas has two sizes: the CSS size (how much room it takes) and the backing store (width and height, how many pixels it holds). On a screen with a device pixel ratio of 2 the box covers 2 by 2 device pixels per CSS pixel, so a 200 by 60 backing store is stretched to 400 by 120 and looks soft. Set the backing store to the CSS size times the ratio and call ctx.scale(ratio, ratio) once (Topic 11.4). If you forget the scale, the drawing fills only a quarter of the box.

6. 6

   The chart that is wrong but looks fine is the dangerous one. No error, a plausible picture. The third example lists the usual suspects: a time-zone day bucket (a trip at 00:30 UTC on 15 January is still 14 January in the Azores), a cut baseline (13.8 times instead of 1.3 times), and unsorted data given to a bisector (it returns index 0 where the answer is 1). Defence: assert what you can (sorted, Number.isFinite), compute a ratio and compare it with the data, and test with a fixed time zone.

• ↔

  Guards that log NaN on every draw cost a little time, so run them in development and in tests, not in a hot production loop.

• ↔

  Dropping bad rows keeps the chart clean but hides data problems; showing them as flagged marks or a count keeps trust. Say what you chose.

• I can describe the five-step method and change one thing at a time.

• I can trace a NaN attribute back to the datum and the raw input.

• I can diagnose a blank SVG with the size, selection and position questions.

• I can size a canvas for the device pixel ratio and say what breaks without the scale.

• I can name three ways a chart is wrong with no error, and a check for each.