What a formatter actually does (and where errors survive)
A formatter is a two-stage pipeline. Stage one parses the raw text into a tree of clauses and expressions. Stage two prints that tree back with tidy whitespace. A syntax error lives in stage one — the parser can't build a tree — so stage two never runs on the broken part.
This is why a formatter can be a diagnostic even though it isn't a fix. If the tool cleanly reformats your query, the SQL is at least grammatically valid — any remaining problem is semantic (wrong column name, type mismatch) and lives in your database, not your syntax. If the tool errors or does nothing, you have a grammar error to hunt down.
Symptom → cause → fix: the errors a formatter exposes but won't repair
When a formatter refuses to run — or the database throws an error the formatter can't help with — the cause is almost always one of these recurring patterns. Match your symptom to the row.
| Symptom | Likely cause | Fix |
|---|---|---|
| Formatter output is identical to input | Query failed to parse; tool passed text through | Run the query in your DB and read the engine's error; fix the grammar, then re-format |
| "Unexpected token near X" | Missing comma between columns, or a reserved word used as an unquoted identifier | Add the comma, or quote the identifier ("order", `order`, [order] per dialect) |
| Error reported at the end of the statement | Unclosed parenthesis or quote earlier in the query | Count opening vs. closing ( and '; the imbalance is above the reported line |
| "Syntax error at or near SELCT / FORM / WERE" | Misspelled keyword | Correct the keyword spelling; formatters don't spell-check |
| JOIN parses but returns a cross product | Missing ON / USING clause | Add the join condition; the formatter aligned it but can't invent it |
| Trailing comma before FROM | Dangling comma in the SELECT list | Delete the comma after the last column |
| Works in one tool, errors in another | Dialect mismatch (Postgres ::cast, MySQL backticks, T-SQL TOP) | Set the formatter to your actual dialect before running |
| Column "does not exist" at execution, formats fine | Semantic error, not syntax | Formatter can't help — check schema, spelling, and table aliases |
The pattern to internalize: rows where the formatter itself balks (identical output, unexpected token, dialect mismatch) are grammar problems the formatter is allowed to notice. Rows where the query formats cleanly but still fails (missing ON, nonexistent column) are semantic problems the formatter is structurally blind to.
The one thing formatters do help with: making errors visible
A formatter can't fix a broken query, but running valid-but-ugly SQL through one is one of the fastest ways to find the break. Collapse a 40-line query onto one line and a missing comma hides in plain sight. Expand it with one column per line and consistent indentation, and the dangling comma, the parenthesis that closes one level too early, and the JOIN with no ON all stand out. That's the honest value proposition: formatters don't debug your SQL, they make your SQL debuggable.
Workflow that actually works:
- Get it to parse. Fix obvious grammar with the database's error message as your guide — it names the failing token.
- Format it. Now that it parses, beautify it so the structure is visible.
- Read the structure. Mismatched parentheses and missing clauses are obvious in well-indented SQL.
- Re-run. Semantic errors (bad columns, type mismatches) surface at execution — the formatter is done helping by this point.
Doing these in order matters. Formatting before the query parses — with a tool lenient enough to reshape invalid input — can smear whitespace across the broken section and bury the original mistake.
Related reading
Once the query parses, formatting is about readability and consistency, not correctness. For that side of the story see SQL formatting best practices and the question of whether formatting changes how a query executes (it doesn't — the engine ignores whitespace). For structuring complex queries, learn about CTEs and how to format them and formatting CASE statements and conditional logic.
Conclusion
A SQL formatter is a beautifier, not a debugger. It parses valid SQL and prints it cleanly; it does not add missing commas, close stray parentheses, or correct misspelled keywords. Its real contribution to debugging is indirect but genuine: a clean format either confirms your syntax is valid or, by refusing to run, tells you it isn't — and well-indented SQL makes the remaining structural mistakes easy to see. Fix syntax first with your database's error message, then format for clarity. Paste a query into the formatter above to see which side of that line yours falls on.