From 7646cd84f9f4b19134e8c3ec3bd9806ad6b92851 Mon Sep 17 00:00:00 2001 From: Guy Korland Date: Sat, 2 May 2026 19:22:09 +0300 Subject: [PATCH 1/2] docs(operations): add Troubleshooting page Create a troubleshooting hub at operations/troubleshooting.md aggregating common issues: - Connection issues (refused, NOAUTH, MOVED redirect) - Query issues (timeout, graph not found, slow queries) - Memory issues (OOM, QUERY_MEM_CAPACITY) - Docker issues (container exits, data loss, Browser access) - Replication issues (replica not syncing) - Kubernetes issues (CrashLoopBackOff) Also adds Troubleshooting to the Operations index page. Addresses audit item P2.2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- operations/index.md | 4 + operations/troubleshooting.md | 290 ++++++++++++++++++++++++++++++++++ 2 files changed, 294 insertions(+) create mode 100644 operations/troubleshooting.md diff --git a/operations/index.md b/operations/index.md index 062a9d0c..09735799 100644 --- a/operations/index.md +++ b/operations/index.md @@ -60,3 +60,7 @@ Comprehensive guides for migrating your data to FalkorDB from RedisGraph, Neo4j, ## 12. [Building Docker](/operations/building-docker) Build custom FalkorDB Docker containers from source with platform-specific examples. + +## 13. [Troubleshooting](/operations/troubleshooting) + +Common issues and solutions covering connection errors, query timeouts, out-of-memory problems, Docker, replication, and Kubernetes troubleshooting. diff --git a/operations/troubleshooting.md b/operations/troubleshooting.md new file mode 100644 index 00000000..558b7f5b --- /dev/null +++ b/operations/troubleshooting.md @@ -0,0 +1,290 @@ +--- +title: "Troubleshooting" +parent: "Operations" +nav_order: 14 +description: "Common FalkorDB issues and solutions covering connection errors, query timeouts, out-of-memory problems, replication, cluster, Docker, and Kubernetes troubleshooting." +--- + +# Troubleshooting + +This page covers the most common issues encountered when running FalkorDB, along with their solutions. Issues are grouped by category for quick reference. + +--- + +## Connection Issues + +### Connection Refused + +**Symptom:** Client throws `Connection refused` or `Could not connect to FalkorDB at localhost:6379`. + +**Possible Causes:** +1. FalkorDB is not running +2. The port is not exposed or mapped incorrectly +3. A firewall is blocking the connection + +**Solutions:** + +```bash +# Check if FalkorDB is running +docker ps | grep falkordb + +# Verify port mapping +docker port + +# Test connectivity +redis-cli -h localhost -p 6379 ping +``` + +If using Docker Compose, ensure the `ports` section maps the correct host port: + +```yaml +ports: + - "6379:6379" +``` + +### Authentication Required / NOAUTH + +**Symptom:** `NOAUTH Authentication required` or `ERR invalid password`. + +**Solutions:** +- Ensure your client provides the correct password set via `--requirepass` +- If using ACL users, authenticate with both username and password +- Check that the ACL file is mounted correctly if users are not persisting + +```python +# Python — provide password +db = FalkorDB(host='localhost', port=6379, password='yourpassword') + +# With ACL user +db = FalkorDB(host='localhost', port=6379, username='myuser', password='mypassword') +``` + +### MOVED Redirect (Cluster Mode) + +**Symptom:** `MOVED 12345 10.0.0.2:6379` error when executing queries. + +**Cause:** Your client is connecting to a cluster node that doesn't own the hash slot for the requested graph. + +**Solution:** Use a cluster-aware client that handles MOVED redirections automatically, or connect to the correct node. See [Setting Up a Cluster](/operations/cluster) for details. + +--- + +## Query Issues + +### Query Timeout Exceeded + +**Symptom:** `Query timed out` error. + +**Cause:** The query execution exceeded the configured timeout. + +**Solutions:** + +1. **Check the current timeout settings:** + + ``` + GRAPH.CONFIG GET TIMEOUT_DEFAULT + GRAPH.CONFIG GET TIMEOUT_MAX + ``` + +2. **Increase the timeout** (if the query legitimately needs more time): + + ``` + GRAPH.CONFIG SET TIMEOUT_DEFAULT 10000 + ``` + +3. **Optimize the query** — use [GRAPH.EXPLAIN](/commands/graph.explain) to inspect the query plan and add indexes where needed: + + ``` + GRAPH.EXPLAIN myGraph "MATCH (n:Person {name: 'Alice'}) RETURN n" + ``` + +4. **Override timeout per-query:** + + ``` + GRAPH.QUERY myGraph "MATCH (n) RETURN n LIMIT 100" TIMEOUT 30000 + ``` + +See [Configuration — Timeouts](/getting-started/configuration#timeout_default) for more details. + +### Graph Not Found + +**Symptom:** `ERR Invalid graph operation on empty key` or similar. + +**Cause:** The graph key does not exist — it may not have been created yet, or the name is misspelled. + +**Solution:** + +``` +# List all graphs +GRAPH.LIST +``` + +Verify the graph name matches exactly (graph names are case-sensitive). + +### Slow Queries + +**Symptom:** Queries take longer than expected. + +**Diagnostic Steps:** + +1. **Check the slow log:** + + ``` + GRAPH.SLOWLOG myGraph + ``` + + This shows queries that took ≥ 10 ms. + +2. **Profile the query:** + + ``` + GRAPH.PROFILE myGraph "MATCH (n:Person)-[:KNOWS]->(m) WHERE n.name = 'Alice' RETURN m" + ``` + + Look for full graph scans — these indicate a missing index. + +3. **Add an index** if the query filters on a property: + + ``` + GRAPH.QUERY myGraph "CREATE INDEX FOR (n:Person) ON (n.name)" + ``` + +See [Range Indexes](/cypher/indexing/range-index) and [GRAPH.PROFILE](/commands/graph.profile) for more details. + +--- + +## Memory Issues + +### Out of Memory + +**Symptom:** `OOM command not allowed when used memory > maxmemory` or query fails with memory allocation error. + +**Possible Causes:** +1. The graph exceeds available memory +2. A single query allocates too much memory + +**Solutions:** + +1. **Check memory usage:** + + ``` + GRAPH.MEMORY myGraph + INFO memory + ``` + +2. **Limit per-query memory:** + + ``` + GRAPH.CONFIG SET QUERY_MEM_CAPACITY 1073741824 # 1 GB + ``` + +3. **Increase the server memory limit** (if resources are available): + + ``` + CONFIG SET maxmemory 8gb + ``` + +4. **Optimize your data model** — remove unnecessary properties, use shorter string values, or split into multiple graphs. + +See [GRAPH.MEMORY](/commands/graph.memory) and [Configuration — QUERY_MEM_CAPACITY](/getting-started/configuration#query_mem_capacity) for details. + +--- + +## Docker Issues + +### Container Exits Immediately + +**Symptom:** Container starts and stops within seconds. + +**Diagnostic Steps:** + +```bash +# Check container logs +docker logs + +# Run interactively to see errors +docker run -it --rm falkordb/falkordb:latest +``` + +**Common causes:** +- Invalid `REDIS_ARGS` or `FALKORDB_ARGS` environment variables +- Missing ACL file when `aclfile` directive is set +- Port conflicts with another service + +### Data Lost After Container Restart + +**Cause:** Data is stored inside the container filesystem, which is ephemeral. + +**Solution:** Mount a persistent volume: + +```bash +docker run -p 6379:6379 -p 3000:3000 \ + -v falkordb-data:/data \ + --rm falkordb/falkordb:latest +``` + +See [Data Durability](/operations/durability) and [Docker Deployment](/operations/docker) for full persistence configuration. + +### Browser Not Accessible + +**Symptom:** Cannot reach the FalkorDB Browser at `http://localhost:3000`. + +**Check:** +1. Ensure port 3000 is mapped: `-p 3000:3000` +2. If using `falkordb/falkordb-server` image — this image does **not** include the Browser. Use `falkordb/falkordb` instead. +3. Check firewall rules if accessing remotely. + +--- + +## Replication Issues + +### Replica Not Syncing + +**Symptom:** Replica shows stale data or `master_link_status:down`. + +**Diagnostic Steps:** + +```bash +# On the replica +redis-cli INFO replication +``` + +**Check:** +- Network connectivity between primary and replica +- Authentication — replica must use the primary's password via `--masterauth` +- The primary is not at max memory / max clients + +See [Configuring Replication](/operations/replication) for setup details. + +--- + +## Kubernetes Issues + +### Pod CrashLoopBackOff + +**Symptom:** FalkorDB pod repeatedly crashes. + +**Diagnostic Steps:** + +```bash +kubectl logs --previous +kubectl describe pod +``` + +**Common causes:** +- Insufficient memory requests/limits — FalkorDB needs enough memory for the graph data +- PersistentVolumeClaim not bound +- Incorrect module path in `--loadmodule` flag + +See [Deploy FalkorDB to Kubernetes](/operations/k8s-support) and [KubeBlocks](/operations/kubeblocks) for deployment guides. + +--- + +## Getting More Help + +If your issue is not covered here: + +1. **Check the logs** — FalkorDB and Redis logs often contain detailed error messages +2. **Search existing issues** on [GitHub](https://github.com/FalkorDB/FalkorDB/issues) +3. **Join the community** on [Discord](https://discord.gg/ErBEqN9E) +4. **Contact support** — [FalkorDB Support](https://www.falkordb.com/contact-us/) From b2bfe7a44ad7b30bd414af648086f035e0c403ca Mon Sep 17 00:00:00 2001 From: Guy Korland Date: Sat, 2 May 2026 20:23:45 +0300 Subject: [PATCH 2/2] docs(troubleshooting): add technical terms to spellcheck wordlist Add NOAUTH, redirections, CrashLoopBackOff, PersistentVolumeClaim to .wordlist.txt to fix check-spelling CI failure on operations/troubleshooting.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .wordlist.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index bbd34ca4..25ae3ce3 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -833,3 +833,7 @@ erroring namespaces tracebacks eval +NOAUTH +redirections +CrashLoopBackOff +PersistentVolumeClaim