Over the years of working in the software industry I have developed a single rule for myself when trying to debug, figure out why something is broken or doesn’t work. I can’t count the number of times not following my rule has come to bite me and led to countless hours of banging my head against the wall.
“Check The Basics”
Check the absolute basics before diving deeper in deeper into debugging a problem with various other tools. In my experience an extremely high percentage of times the problem is due to some form of human error or something primitive like “is it on?”
Here is an example of a problem I ran into last week and spent hours debugging. Unfortunately, I did not follow my own rule carefully and was reminded of it after resolving the issue. I use Docker on an ARM64 Mac and that could sometimes require setting platform flags when building and/or running containers between ARM and x86 architectures.
I wrote my Dockerfile, added an entrypoint.sh script, built my container, and when I ran the container, I got an error:
exec ./entrypoint.sh: exec format error
Googling around, the exact error is most common due to platform mix-ups, so I begin toggling platform flags on how I am building and running the container without resolution. It gets even stranger, because if I override the entry point and execute the entrypoint.sh from inside the container the script runs fine. After:
- Rebuilding the container several times with various combinations of platform flags
- Inspecting and even switching my Mac Docker runtimes
- Running in native Docker on a Linux VM
- More time spent Googling around
I ran out of ideas, so I asked my colleague for help and to look at my entrypoint.sh script. As I do Command+a to copy and paste the script to him I see it:
#!/usr/bin/env bash
...
Is that space character before the shebang really the problem? It sure is! Check the basics! I’m not sure how it got in there, but we see another case where the problem was not difficult at all to solve, just harder to spot without first checking the absolute basics.