Lesson 05 of 7 · Reading a failure

A good failure tells you where to look.

When I say FAIL, I say where and why. Your job is to read me top-down and find the first cause.

with Elizabeth Cecilia. About 8 minutes. Tap any for its meaning.

Explore

Anatomy of a failure

This is real output from a deliberately broken copy, with the names changed. Tap each highlighted part.

PS> python tools/validate.py report optional page not built: Regional view :

Part

Tap a part of the output

1 failure and 1 warning. Can you carry on to Desktop?

Predict first

Five FAILs, one cause

checks passed: 1234 FAIL model/Sales.tmdl: column Region is in the spec but not declared FAIL relationship Sales[Region] to Region[Region] not found FAIL visuals/v02: tile 'Sales by region' uses Sales[Region], not in model FAIL visuals/v05: tile 'Top regions' uses Sales[Region], not in model FAIL visuals/v07: slicer 'Region' uses Sales[Region], not in model

Which do you fix first?

Triage

Fix the file, fix the spec, or carry on?

A FAIL means the files and the disagree. Usually the file is wrong, but not always.

WARN optional page not built

FAIL card needs textWrap as the seed writes it (the agent missed one card)

FAIL page has 6 data visuals, spec says 7 (you removed one on purpose today)

FAIL visual.json is not valid JSON

Check

Fix forward or roll back?

One FAIL, in one small file, and you can see exactly why.

After regenerating every page: 140 FAILs across files you didn't expect to change.

Recap

Three things to keep

1A good FAIL line names the file, the thing and the rule. You shouldn't have to search.
2Read FAILs top-down and look for the : fix the first cause, not every symptom.
3A FAIL means file and spec disagree. Usually fix the file; sometimes the spec is what's out of date.