Read error messages literally
Most debugging fails at the first sentence: the tool said what was wrong and the reader substituted what they expected. This skill forces a byte-level reading of the message before any theory is allowed.
Procedure
Capture the full message, not the last line. Re-run the failing command with stderr attached:
./build.sh 2>&1 | tee /tmp/err.txt, then read it back withread_file("/tmp/err.txt").Quote the exact string in your working notes. Do not paraphrase; the wording carries the signal.
Decompose the message into literal parts: error code, path, line number, offending token, and which program emitted it.
For a stack trace, read upward from the last line — that is the raising frame, not necessarily the root cause.
pytest -x -q --tb=longprints the assertion and the frame that failed it.Resolve every path the message names:
ls -l /etc/ssl/certs/ca.pemto confirm the file exists or does not. Do not assume existence either way.Check the numeric exit status separately:
echo $?. 127 means command not found, 126 not executable, 137 killed (SIGKILL), 139 segfault — map the number before theorising.Only when every literal token in the message is accounted for do you propose a cause. If your cause does not explain each token, it is wrong.
Re-run the exact minimal command after any fix and paste the new output; never assume a fix worked because it seems right.
Pitfalls
- "Connection refused" and "connection timed out" are different faults; conflating them sends you to the wrong layer.
- Truncated logs hide the real line; check
wc -l /tmp/err.txtagainst the log's own reported total. - A missing-file error may be a symptom of an earlier step that wrote to the wrong working directory.
- Trailing whitespace or a smart quote in the message is a hint, not noise.
- A stack trace truncated by a log rotation can end mid-frame; confirm you have the complete record.
Verification
./build.sh 2>&1 | tail -5; echo "exit=$?"
Report the exact string, the exit code, and each resolved path — never a paraphrase of the error.