Minutes on the Matter of YAML Indentation
The deployment failed. The error message names line 47. Line 47 looks fine. Three people have looked at line 47 and agree that it looks fine. It is not fine.
MINUTES OF THE YAML INDENTATION INCIDENT TIME: 2:47pm to 2:55pm, eight minutes total
2:47pm: Deployment pipeline reports failure. Error: yaml parse error near line 47. The team is notified.
2:48pm: Line 47 is examined by the person who wrote the configuration file. The key-value pair is correct. The colon is correctly placed. The value is of the right type. The line looks right.
2:49pm: The parser's complaint is noted. The parser is not known to complain frivolously.
2:50pm: A second person checks line 47. That person notes that the line appears to follow the structure established in preceding lines and cannot identify the error.
2:51pm: The indentation level of line 47 is counted. Two spaces. The indentation level of the parent element is counted. Also two spaces. The indentation level of sibling elements is counted. Two spaces. Everything appears consistent.
2:51:30pm: The indentation of the actual spaces on line 47 is counted again using cursor movement. Four spaces. The visual rendering had collapsed the difference. The parent uses two spaces. Line 47 uses four. Four is not two.
2:52pm: The indentation is corrected.
2:54pm: The file is accepted by the parser.
2:55pm: The service is deployed.
Post-Incident Note
The error was two spaces. Two spaces rendered the file structurally invalid because YAML uses indentation as its only syntax for expressing hierarchy. A key at the wrong indentation level belongs to the wrong parent. The parser cannot proceed.
The error was invisible to three human readers at normal reading speed. It was immediately visible when counted.
Recommendation: use a YAML linter. The linter counts spaces. The linter does not find them visually correct. The recommendation will be added to the backlog. The backlog is a YAML file.