# Debug

Debug FalkorDB crashes, hangs, panics, and incorrect query results - attach lldb/gdb to...

- Repository: https://github.com/FalkorDB/FalkorDB (10505 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add FalkorDB/FalkorDB --skill debug -g -a claude-code -y`
Codex: `npx skills add FalkorDB/FalkorDB --skill debug -g -a codex -y`
Cursor: `npx skills add FalkorDB/FalkorDB --skill debug -g -a cursor -y`
Gemini CLI: `npx skills add FalkorDB/FalkorDB --skill debug -g -a gemini-cli -y`

## Description

Debug FalkorDB crashes, hangs, panics, and incorrect query results - attach lldb/gdb to redis-server with the module loaded, understand panic/crash behavior, step through query execution, and triage failing CI runs. Use when investigating a crash, hang, wrong query result, or a red CI job.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Debug

## 1. Attach a debugger to the module

Build a debug binary first (`cargo build`), then launch `redis-server` with
the module loaded under a debugger (mirrors `.vscode/launch.json`):

```bash
# macOS
lldb -- redis-server --loadmodule target/debug/libfalkordb.dylib

# Linux
lldb -- redis-server --loadmodule target/debug/libfalkordb.so
# or: gdb --args redis-server --loadmodule target/debug/libfalkordb.so
```

Then `run` inside the debugger, reproduce the issue from a second terminal
with `redis-cli` (or the failing test/query), and let it trap on
crash/signal. Use `bt` (backtrace), `frame select`/`up`/`down`, and
`thread list` to inspect the failure. Swap `target/debug` for
`target/release` to debug a release build instead.

For a specific failing flow test under the debugger, use RLTest directly
instead of `flow.sh` so it doesn't spawn/manage the server itself (activate
the venv first so `python -m RLTest` resolves, it lives at `/data/venv` in
the devcontainer/CI):
```bash
source venv/bin/activate 2>/dev/null || source /data/venv/bin/activate
lldb -- python -m RLTest --test tests/flow/<file>.py --module target/debug/libfalkordb.so --no-progress -v
```

## 2. Understand crash/panic behavior before you dig in

The rest: https://github.com/FalkorDB/FalkorDB/blob/HEAD/.claude/skills/debug/SKILL.md