I Got Tired of Googling ShellCheck Errors. So I Built a Decoder.

#bash #linux #shellcheck #devops

It happened on a Tuesday at 10pm.

I was trying to get a CI pipeline to pass, and ShellCheck was firing on my deploy script. The error read:

deploy.sh line 14: SC2086: Double quote to prevent globbing and word splitting.

I knew of SC2086. I'd seen it before. I had no idea what "globbing and word splitting" actually meant in this specific context, which variable was the problem, or how to fix it without breaking the logic I'd already written.

So I did what everyone does: opened a browser tab, searched "SC2086 bash fix", ended up on four different pages, none of which had a before/after example that matched what I was looking at, and spent 35 minutes fixing a bug that should have taken 3.

That's the problem with ShellCheck. The tool itself is excellent — it catches real bugs that would have bitten me in production. But the error codes are opaque. SC2086, SC2046, SC2034, SC2181 — these are not self-explanatory. And when you're staring at one at 10pm with a deploy blocked, "go read the wiki" doesn't cut it.

So I built the ShellCheck Error Decoder — a free interactive tool that translates ShellCheck codes into plain English explanations with before/after fix examples, right in the browser.

What the Tool Does

Input is flexible. You can type just the code number (SC2086), paste a bare number without the prefix (2086), or paste the entire line ShellCheck spits out verbatim:

deploy.sh line 14: SC2086: Double quote to prevent globbing and word splitting.

The tool detects whichever format you're using and resolves it automatically. No reformatting required. If you paste output with multiple SC codes in one block, it detects all of them and lets you click each one individually — no need to isolate a single code first.

The result card shows you four things:

Plain English explanation — not the wiki's technical summary, an actual sentence that tells you what's wrong with your script
Severity badge — color-coded by ShellCheck's own severity level: 🔴 ERROR, 🟡 WARNING, 🔵 INFO, ⚪ STYLE. You know immediately if this is going to break your script or just offend a linter
Before/After code block — the broken version and the fixed version, with a copy button on the fixed version
Why it matters — not just "quote your variable" but why an unquoted variable causes a globbing bug and when it would actually blow up on you

Below the result card, there's a disable directive — the exact # shellcheck disable=SC2086 comment you need to suppress the warning on a specific line, with a copy button. For the cases where you've made a deliberate choice and ShellCheck needs to back off.

The Browseable Category Filter

One of the features I kept wanting while building this was a way to see all codes in a category at once — not just look up a single code reactively.

If your script is new and ShellCheck is firing 8 times, you want to understand the pattern, not just fix each warning in isolation.

The tool has a category filter at the top: Quoting, Variables, Logic, Style, Portability. Click any category and the list filters to just those codes. Useful when you're doing a cleanup pass on a script and want to understand an entire class of issues at once instead of chasing them one by one.

The Real-Life SC2086 Example

Here's what SC2086 actually means and why it matters — this is the most common ShellCheck error by a mile.

Broken:

files="report.txt notes.txt backup.tar.gz"
rm $files

Fixed:

files="report.txt notes.txt backup.tar.gz"
rm "$files"

Looks almost identical. The difference matters because of how bash expands unquoted variables. Without the quotes, bash doesn't treat $files as a single string — it performs word splitting on whitespace, then glob expansion on any *, ?, or [ characters in the result.

So if your variable happens to contain a *, unquoted $files becomes rm * — which removes every file in the current directory. This is not hypothetical. This has caused real data loss on real servers. The fix is two characters: "$files".

That's what the tool explains in the Why it matters section. Not just the fix, but the actual mechanism so you understand why quoting matters and stop skipping it when you're in a hurry.

Codes Covered

The tool currently covers 30 of the most common ShellCheck codes — the ones that account for the vast majority of real-world hits:

Code	What it catches
`SC2086`	Unquoted variable — globbing/word splitting risk
`SC2046`	Unquoted command substitution — same risk, different form
`SC2034`	Unused variable — assigned but never used
`SC2155`	Declaring and assigning in one line — hides exit codes
`SC2154`	Variable referenced but not assigned
`SC2164`	`cd` without checking if it succeeded
`SC2006`	Backtick command substitution — use `$()` instead
`SC2162`	`read` without `-r` — mangles backslashes
`SC2181`	Checking `$?` after an `if` — use `if cmd; then` instead
`SC2016`	Expressions inside single quotes don't expand

Each one has a before/after example, a plain English explanation, a severity badge, and a disable directive. The official wiki link is in every result card for when you want the full technical writeup — but the goal is that you won't need it for the common cases.

Try It

bashsnippets.xyz/tools/shellcheck-error-decoder.html

Free. No account. No email. Works in the browser. The input field is focused on page load so you can paste your error code immediately.

If there's a code you hit frequently that isn't in the decoder yet, drop it in the comments — coverage grows based on what people actually run into in production.

The Broader Context

The ShellCheck decoder is part of the free tools directory at BashSnippets.xyz/tools. The rest of the suite:

Bash Exit Code Lookup — same idea but for exit codes 0–255. What does exit code 141 mean? Look it up, get a generated error handler.
Cron Job Builder — build cron syntax visually, preview the next 5 scheduled runs before you commit
Chmod Permissions Builder — click checkboxes, get the octal number
PATH Debugger — diagnose command-not-found errors by walking your $PATH
Bash Boilerplate Generator — configure your script header and get a production-ready .sh template