🚨 VictoriaMetrics Error Guide: 'cannot parse MetricsQL' — Fix Broken Query Syntax

Overview

When VictoriaMetrics cannot compile a query string into a valid MetricsQL expression, it rejects the request with HTTP 422 and a parse error that pinpoints the offending position:

cannot parse "sum(rate(http_requests_total[5m]) by (job)": missing `)` in front of "by (job)"; unparsed data: "by (job)"

MetricsQL is a superset of PromQL, so most PromQL parses fine, but the error is unambiguous: the text you sent is not syntactically valid. The message tells you exactly what token it choked on and what it expected, which makes these among the fastest VictoriaMetrics errors to fix.

Symptoms

• Grafana panels or vmalert rules return HTTP 422 Unprocessable Entity with cannot parse.
• The error quotes your query and points at an unparsed data: fragment.
• A query that worked in another tool fails after copy-paste (smart quotes, stray newline).
• vmalert refuses to load a rule file, logging the parse failure and the rule name.
• Templated Grafana variables expand into malformed expressions.

Common Root Causes

• Unbalanced brackets or parentheses — a missing ) or ], as in rate(...[5m] without closing, or an aggregation placed outside its parentheses.
• Malformed label matchers — missing quotes ({job=api} instead of {job="api"}) or an unclosed {.
• Invalid duration literals — [5] or [5 m] instead of [5m]; ranges need a unit (s, m, h, d, w, y).
• Smart quotes / hidden characters — copy-paste turns " into “ ”, or a non-breaking space sneaks in.
• Template-variable expansion — a Grafana $var resolving to an empty or multi-value string that breaks syntax.
• PromQL constructs MetricsQL still needs quoting — unquoted string arguments or a misplaced by/without clause.

Diagnostic Workflow

Read the error literally — it names the position. Reproduce it with a direct API call so you see the raw response, not Grafana’s wrapper:

curl -s 'http://localhost:8428/api/v1/query' \
  --data-urlencode 'query=sum(rate(http_requests_total[5m]) by (job)'

{"status":"error","errorType":"422","error":"cannot parse ...: missing `)` in front of \"by (job)\""}

Paste the exact query into the vmui query box (http://localhost:8428/vmui) — it highlights syntax and shows the parse error inline as you edit. Fix the balance and re-check:

curl -s 'http://localhost:8428/api/v1/query' \
  --data-urlencode 'query=sum(rate(http_requests_total[5m])) by (job)'

For vmalert rule files, validate before deploying with dry-run:

./vmalert -rule=/etc/vmalert/rules.yml -datasource.url=http://localhost:8428 -dryRun

Strip hidden characters if the query looks correct but still fails:

echo 'sum(rate(http_requests_total[5m])) by (job)' | cat -A

Example Root Cause Analysis

A vmalert deployment failed to start, logging cannot parse "..." : unparsed data. The rule in question was:

expr: sum by(instance) (rate(node_network_receive_bytes_total[5m])) > 1e6 and on(instance) up == 1)

The -dryRun output pointed at a trailing ) with unparsed data: ")". A previous edit had removed an opening parenthesis but left the closing one, leaving the expression unbalanced. Removing the stray ) made the rule compile. The team added vmalert -dryRun to CI so malformed MetricsQL could never reach production again.

Prevention Best Practices

• Author and test every query in vmui first; it reports parse errors live and highlights brackets.
• Run vmalert -dryRun (or the rules linter) in CI so no rule file with invalid MetricsQL is deployed.
• Retype quotes and durations rather than copy-pasting from chat or docs to avoid smart quotes and non-breaking spaces.
• Always quote label matcher values: {job="api"}, never {job=api}.
• Give Grafana template variables sensible defaults and use regex/All handling so expansion never produces empty or malformed text.
• Keep range durations unit-qualified ([5m], [1h]), never bare numbers.

Quick Command Reference

# Reproduce the raw parse error
curl -s 'http://localhost:8428/api/v1/query' \
  --data-urlencode 'query=<your query>'

# Validate alerting rules before deploy
./vmalert -rule=/etc/vmalert/rules.yml \
  -datasource.url=http://localhost:8428 -dryRun

# Reveal hidden/non-breaking characters
echo '<your query>' | cat -A

# Interactive query editor
# open http://localhost:8428/vmui

Conclusion

cannot parse MetricsQL is the most self-explanatory error VictoriaMetrics produces: it quotes your query and marks the exact token it could not parse. Nearly every case is an unbalanced bracket, an unquoted label, a bad duration, or a smart-quote from copy-paste. Build queries in vmui, gate rule files with vmalert -dryRun, and the class of error disappears from production entirely.