Skip to content
Tutorials Center
My learning

Topics

Lesson 39 of 39 ยท Projects and Practice

Troubleshooting InfluxDB

A practical checklist for common InfluxDB problems: missing points, write errors, slow queries, memory growth, disk usage and wrong results, with a runnable diagnostic tool.

Sooner or later something will not work: a graph is empty, a write returns an error, a query takes a minute, disk fills up. Most InfluxDB problems fall into a short list of causes. This closing lesson gives you a systematic checklist so that you diagnose instead of guess.

The InfluxDB server is not available in this course, so the commands are read-only examples, and the one runnable piece is a small diagnostic tool that classifies write errors the way you would by hand. Command names vary by version (2.x uses the influx CLI, 3.x uses influxdb3), so check your version's help.

The method

  1. Reproduce and narrow. Is it writes, queries or the server? One host or all? Since when? What changed?
  2. Check the basics: is the server up, is the disk full, is the clock correct, is the token valid?
  3. Look at the logs and the server's own metrics.
  4. Test with the smallest case: one point written with curl, one query with a tight time range.
  5. Change one thing at a time, and write down what you tried.

Health endpoints are the first stop (read-only):

Terminal
curl -s http://localhost:8086/health            # 1.x / 2.x
curl -s http://localhost:8181/health            # 3.x default port

Problem: data is missing

Walk down this list:

  • Time range. Does your query's range() or WHERE time include the data? The most common cause is querying the wrong window, or timestamps in the future or far past.
  • Timestamps in the wrong precision. Writing seconds while the server expects nanoseconds puts every point in January 1970, outside any range you query. Check the precision parameter.
  • Retention. The point's timestamp is older than the bucket's retention period, so it is dropped.
  • Wrong bucket, database or organization in the write or the query.
  • Not flushed. A batching client has not sent its buffer (batching).
  • Overwritten points. Same series and timestamp overwrote the earlier point (schema design).
  • Type conflict. A field that was a float now gets an integer or string, and the write was rejected.
  • Tag versus field confusion. You filter r.temp == "21" on a field, or r._value on a tag.

Problem: write errors

Response Typical cause Fix
400 Invalid line protocol, field type conflict, point outside retention Fix the data. Look at the error message and the line number it gives
401 Missing or invalid token Use a valid token
403 Token lacks write permission on this bucket Create or edit the token
404 Bucket, database or org not found Check names
413 Body too large Smaller batches
422 Valid syntax but not acceptable, such as a schema or limit violation Read the message
429 Rate or quota limit Back off and retry
500, 503 Server error or overloaded Check logs, retry with backoff

Problem: slow queries

  • Unbounded time range. Always filter by time first.
  • Too many series matched: filter by tags early (cardinality).
  • Querying raw data for a long range. Use a downsampled bucket (downsampling).
  • Pulling everything then filtering. Push filters down to the start of the query.
  • Heavy transforms like pivot() or join() on large inputs in Flux.
  • A tiny window on a long range, producing millions of output points.
  • In InfluxDB 3, use EXPLAIN and EXPLAIN ANALYZE to see the plan.

Problem: memory or disk growth

  • Cardinality explosion: a tag with unbounded values. Find it by checking the distinct values per tag key, fix at the source, and drop the data.
  • Retention too long or infinite for raw data.
  • Failing compaction or a disk with no free space (compaction needs headroom).
  • Large batches and many concurrent queries at once.
  • Tasks or checks that read very long ranges every minute.
  • Look at du of the data directory, per-bucket size reports where available, and the server's own metrics.

Problem: results look wrong

  • Window edges. Flux labels rows with the window stop; SQL date_bin with the start: shifted charts are not wrong, only labelled differently.
  • Average of averages across unequal windows.
  • Time zones. Timestamps are UTC; "today" in your dashboard is not.
  • Counter resets distort raw differences.
  • Null versus zero: a gap is not a zero.
  • Mixing units from different agents.

A diagnostic helper (runnable)

This small JavaScript tool classifies an HTTP status and message from a write, and suggests the next action. It encodes the table above, the kind of rule you could put in a script or runbook.

JS Stand-in: classify a write failure

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A second helper: is the timestamp plausible?

A frequent silent failure is wrong timestamp precision. This function guesses the unit from the magnitude of a number so you can spot a seconds-versus-nanoseconds mix-up.

JS Stand-in: guess the unit of a timestamp

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Prevention

  • Monitor InfluxDB itself: write error rate, query duration, disk free, series count, memory. Alert on them (checks).
  • Back up and test restores (scaling).
  • Document the schema, retention and ownership.
  • Test configuration changes in a staging bucket.
  • Keep versions current, reading release notes before upgrades.
  • Write a runbook for the top five failures, using the checklist above.

When to ask for help

Share the version, the exact error text, a minimal query or line-protocol sample, and what you already tried. Remove tokens and private data first. A reproducible small case solves most problems quickly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. All your points are 'missing', but writes return 204. What should you check first?

    Seconds written as nanoseconds land in 1970 and fall outside any recent query range.
  2. 2. Which status should be retried with backoff?

    429 means rate limited, and it can succeed later. The others are errors in the request.
  3. 3. Disk and memory keep growing. What is a likely cause?

    Cardinality explosion and unlimited raw retention are the usual suspects.
  4. 4. What is the best first step when a query is slow?

    Reduce the data scanned before touching hardware.

Summary

  • Diagnose in order: reproduce, check the basics, read logs, test the smallest case.
  • Missing data usually means the wrong time range, precision, bucket, retention or an unflushed client.
  • Classify write errors by status: fix 4xx data errors, retry 429 and 5xx with backoff.
  • Slow or growing systems point to cardinality, unbounded ranges and long retention.
  • Monitor the database itself and keep a runbook.

Next: Back to the InfluxDB course overview