For a long time I assumed bash -n was a reliable oracle.
Run the script through it, if it exits clean the syntax is fine. That’s the deal. I had been using it to validate shell scripts without giving it a second thought.
I was working on the script that runs the agent work board pipeline. I added a block that used a heredoc inside a command substitution, followed later by another quoted one. Completely legal bash. bash -n disagreed. Bogus syntax error, flagged dozens of lines from anything I had touched, pointing at code that looked fine.
Rewrote the block. Different approach, same structure underneath. bash -n still failed. Rewrote it again. Third time. Same error, same line.
That’s where I should have asked which bash I was running.
macOS ships with bash 3.2 from 2007. The 3.2 parser has a known problem when a heredoc inside $() is followed later in the same script by a quoted $() one-liner. It loses track of quote state and flags a spurious error far from the actual syntax. Bash 5 on Ubuntu handles identical code without complaint, and I have an Ubuntu box on EC2 for exactly this, ec2-Klaus. I scp’d the script over, ran bash -n there, and it passed clean. Zero errors. Same file.
Three rewrites. The code was right the whole time.
Every rewrite was adding noise, swapping correct syntax for other correct syntax, while the actual problem sat upstream of the script entirely. The authoritative bash for scripts that run on ec2-Klaus is bash 5 on that Ubuntu box, not whatever shipped with macOS in 2007 and never got updated.
I would have scp’d the file after the first rewrite.