arrow-leaks

Diagnose Apache Arrow memory leak errors in XTDB tests and nodes.

3.0k|192|Updated Mar 19, 2018
One-click install
npx skills add https://github.com/xtdb/xtdb --skill arrow-leaks
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: arrow-leaks
Source: https://github.com/xtdb/xtdb/tree/main/.claude/skills/arrow-leaks
Command: npx skills add https://github.com/xtdb/xtdb --skill arrow-leaks

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Arrow "Memory was leaked" errors report the close-time detection stack rather than the actual allocation site, making leaks hard to trace. This Skill explains how to enable Arrow's debug allocator in XTDB's Gradle build, identify the failure-path cleanup gaps that cause most leaks, and avoid misattribution from property-test shrinking.

Core Features & Use Cases

  • Debug Allocator Setup: Explains why -D flags and JAVA_TOOL_OPTIONS fail, and how to flip arrow.memory.debug.allocator in build.gradle.kts defaultJvmArgs to capture allocation stack traces.
  • Leak Pattern Recognition: Identifies common XTDB leak causes such as openSlice results handed off without .use or closeOnCatch on throwing code paths.
  • Property-Test Guidance: Shows how to bisect leaks across commits at high -Piterations and confirm single-op reproductions with a plain deftest, avoiding the shrinker's misleading :smallest case.
  • Use Case: A CI test run reports leaked Arrow memory naming the leader-log-processor allocator; use this Skill to enable the debug allocator, locate the orphaned buffer in the transaction indexing path, and write a minimal reproducing test.

Quick Start

Ask the assistant to help track down the Arrow memory leak reported by your failing XTDB test, starting by enabling the debug allocator in build.gradle.kts.

Frequently Asked Questions about arrow-leaks

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find the allocation site of an Arrow memory leak?

Enable Arrow's debug allocator so the leak error gains an event log section with ALLOCATE stack traces pointing to the allocation site. In XTDB, flip `arrow.memory.debug.allocator` to true in build.gradle.kts defaultJvmArgs, since command-line -D flags and JAVA_TOOL_OPTIONS are overridden.

Why does the Arrow memory leak error show the wrong stack trace?

The error carries the close-time detection stack, not the allocation site where the buffer was created. Only the debug allocator records per-allocation stacks, which is why it must be enabled to trace the leak's origin.

Why doesn't JAVA_TOOL_OPTIONS enable the Arrow debug allocator in XTDB?

XTDB's build.gradle.kts pins `-Darrow.memory.debug.allocator=false` in defaultJvmArgs, which every Test, JavaExec, and clojureRepl task inherits. That pinned value overrides anything passed via command line or environment variables.

What causes most Arrow memory leaks in XTDB?

Most leaks are failure-path cleanup gaps: a buffer is opened, then an exception unwinds past its close. Look for openSlice and other open calls whose result is handed off without a .use or closeOnCatch on a path that can throw.

Why does property-test shrinking point at the wrong operation for leaks?

The shrinker assumes determinism that leaks do not have, so its :smallest case can misattribute the leak. Bisect with the property test across commits at high -Piterations, then confirm with a single-op plain deftest under the debug allocator.

Should the Arrow debug allocator stay enabled in production?

No. The debug allocator performs per-allocation bookkeeping that adds overhead, so it should only be enabled while hunting a leak. Flip the build.gradle.kts entry back to false before committing.