Debugging

This page collects the debugging workflows that DuckDB maintainers actually use.

Pick the right build

Build	Optimizations	Asserts	Sanitizers	Use when
make (release)	-O3	off	off	Reproducing a customer-reported bug at speed.
make reldebug	-O2	on	off	Day-to-day development.
FORCE_DEBUG=1 make relassert	-O2	on	on (UBSan/ASan)	Investigating heisenbugs and undefined behavior.
make debug	-O0	on	on	Step-debugging in gdb/lldb, slow but easiest to read.

reldebug is the right default. Use relassert when you suspect undefined behavior.

Step debugging

gdb --args build/debug/duckdb mydatabase.db
(gdb) break duckdb::ClientContext::ExecuteInternal
(gdb) run
(gdb) c

LLDB equivalents work too. The default symbol level on debug and reldebug is sufficient for breakpoints in any C++ symbol.

Sanitizers

The debug and relassert builds enable UBSan/ASan via CMake (-fsanitize=undefined,address). To suppress known leaks, see .sanitizer-leak-suppressions.txt and .sanitizer-thread-suppressions.txt at the repository root. ThreadSanitizer (-fsanitize=thread) is enabled by make tidy-check and the sanitizer-specific CI jobs.

Pre-set suppressions:

• Leak suppressions: .sanitizer-leak-suppressions.txt
• Thread suppressions: .sanitizer-thread-suppressions.txt

Reproducing on a different storage version

# build a database with the v1.0 format
DUCKDB_STORAGE_VERSION=v1.0.0 build/reldebug/duckdb my.db
# then read it with the current build
build/reldebug/duckdb my.db

For storage compatibility, see scripts/test_storage_compatibility.py and test/bwc/.

Logging

DuckDB ships a structured logger in src/logging/. Configure it in SQL:

PRAGMA enable_logging;
PRAGMA log_query_path='/tmp/duckdb.log';

Or via the C API: DuckDBLogger/DuckDBLogContext in src/main/capi/logging-c.cpp. Programmatic control lives in src/logging/. The internal LogManager and LogStorage types are documented at src/include/duckdb/logging/.

Profiling

Enable profiling in a session:

PRAGMA enable_profiling = 'json';
PRAGMA profile_output = '/tmp/profile.json';

SELECT ...;

Profiles are emitted by src/main/query_profiler.cpp. The EXPLAIN ANALYZE form prints a tree-rendered profile inline:

EXPLAIN ANALYZE SELECT ...;

To see the rendered tree without execution, use plain EXPLAIN:

EXPLAIN SELECT ...;

Render code is in src/common/tree_renderer/.

Common errors

Error	Where to look
Out of Memory Error	Buffer manager limit. Check PRAGMA memory_limit, src/storage/standard_buffer_manager.cpp.
Catalog Error: Table with name X does not exist	src/catalog/catalog_search_path.cpp and the binder (src/planner/binder.cpp). Often a schema/database mismatch.
Binder Error: Could not bind ...	src/planner/expression_binder/. Frequent cause: ambiguous column names; use qualified names.
Conversion Error: ...	Cast rules in src/function/cast_rules.cpp and the cast functions in src/function/cast/.
Constraint Error	src/storage/data_table.cpp (NOT NULL, FOREIGN KEY) and ART index violations in src/execution/index/.
Internal Error	A D_ASSERT or contract violation. Re-run with make debug and capture a stack trace.
Crash mid-query	Most often a NULL Vector / dictionary handling bug. Run with make relassert.

Help from the engine

DuckDB has rich introspection via SQL:

• PRAGMA table_info('t') — column metadata.
• PRAGMA show_databases, PRAGMA show_tables.
• PRAGMA version, PRAGMA platform.
• SELECT * FROM duckdb_settings(), duckdb_functions(), duckdb_extensions(), duckdb_indexes(), …
• CALL pragma_database_size() for storage stats.

These are implemented in src/function/pragma/ and extension/core_functions/. Reading their source is a fast way to find the right introspection table for whatever you are debugging.

Fuzzers

If you suspect a robustness bug, run the fuzzers:

build/reldebug/test/unittest --test-dir test/fuzzer

For OSS-fuzz integration see test/ossfuzz/ and .github/workflows/cifuzz.yml.