Skip to main content
skill CX Codex

nginx-c-module-debug — Claude Code skill: debugging

The nginx-c-module-debug skill guides diagnosis of nginx C module crashes, memory faults, and request-flow problems. Use it for GDB, core dumps, and tracing.

MIT 260 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill nginx-c-module-debug -a claude-code
Open on GitHub

What nginx-c-module-debug does

nginx-c-module-debug gives an agent a structured way to investigate nginx C modules. Its rules cover worker failures such as segfaults, SIGABRT, and SIGSEGV, along with use-after-free, leaks, pool corruption, and buffer overruns. It also follows request phases, subrequests, filters, and upstream callbacks.

The skill contains 45 rules grouped into 8 areas: crash diagnosis, memory bugs, GDB and core dumps, request tracing, debug logging, state and lifecycle checks, dynamic tracing, and sanitizer-oriented build settings. The material includes tasks such as attaching GDB to a worker, reading a backtrace, inspecting ngx_http_request_t, and tracking configuration inheritance.

This is a diagnosis skill, separate from the repository’s skills for module correctness and performance. It can be installed for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

What it helps with

  • analyze a worker crash from its signal and address
  • track down use-after-free and memory leaks
  • set up core dump inspection with GDB
  • trace a request through phases and filters
  • check the upstream callback sequence

Example prompts for the agent

  • Analyze this nginx worker crash from the backtrace and identify the request phase.
  • Inspect this C module for a possible use-after-free and outline a GDB check.
  • Trace the subrequest tree and verify the filter chain order.

How to install nginx-c-module-debug

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill nginx-c-module-debug -a claude-code

2Manually: put the files in place

~/.claude/skills/nginx-c-module-debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nginx-c-module-debug/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nginx-c-module-debug

How do I install nginx-c-module-debug in Claude Code?

Run npx skills add pproenca/dot-skills --skill nginx-c-module-debug -a claude-code, then check ~/.claude/skills/nginx-c-module-debug/SKILL.md.

What does nginx-c-module-debug do?

It guides diagnosis of nginx C module crashes, memory defects, request-flow issues, and production failures. The rules cover GDB, core dumps, debug logging, and tracing.

Which platforms support nginx-c-module-debug?

The skill can be installed for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

Source text

SKILL.md · MIT
---
name: nginx-c-module-debug
description: nginx C module debugging guidelines based on the official nginx development guide. This skill should be used when debugging nginx C module crashes, memory bugs, request flow issues, or production problems. Triggers on tasks involving segfault analysis, coredump debugging, GDB inspection, memory leak detection, request phase tracing, AddressSanitizer setup, or nginx module troubleshooting.
---

# nginx.org C Module Debugging Best Practices

Comprehensive debugging guide for nginx C modules, derived from the official nginx development documentation and production debugging experience. Contains 45 rules across 8 categories, prioritized by impact to guide systematic diagnosis of crashes, memory bugs, and behavioral issues in nginx modules.

**Companion skills**: This skill complements [nginx-c-modules](../nginx-c-modules/SKILL.md) (correctness) and [nginx-c-module-perf-reliability](../nginx-c-module-perf/SKILL.md) (performance). This skill covers **debugging and diagnosis**.

## When to Apply

Reference these guidelines when:
- Diagnosing nginx worker crashes (segfaults, SIGABRT, SIGSEGV)
- Finding memory bugs (use-after-free, leaks, pool corruption, buffer overruns)
- Setting up GDB and core dump analysis for nginx
- Tracing request flow through phases, subrequests, and filter chains
- Instrumenting nginx modules with debug logging and dynamic tracing tools

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Crash Diagnosis & Signals | CRITICAL | `crash-` |
| 2 | Memory Bug Detection | CRITICAL | `memdbg-` |
| 3 | GDB & Core Dump Analysis | HIGH | `gdb-` |
| 4 | Request Flow Tracing | HIGH | `trace-` |
| 5 | Debug Logging Patterns | MEDIUM-HIGH | `dbglog-` |
| 6 | State & Lifecycle Debugging | MEDIUM | `state-` |
| 7 | Dynamic Tracing Tools | MEDIUM | `probe-` |
| 8 | Build & Sanitizer Configuration | LOW-MEDIUM | `build-` |

## Quick Reference

### 1. Crash Diagnosis & Signals (CRITICAL)

- [`crash-segfault-signature`](references/crash-segfault-signature.md) - Identify Segfault Crash Signature from Signal and Address
- [`crash-null-deref-pattern`](references/crash-null-deref-pattern.md) - Recognize NULL Pointer Dereference Patterns in nginx Modules
- [`crash-double-free-finalize`](references/crash-double-free-finalize.md) - Diagnose Double Finalize Crashes from Request Reference Count
- [`crash-stack-overflow`](references/crash-stack-overflow.md) - Detect Stack Overflow from Recursive Subrequest or Filter Chains
- [`crash-worker-exit-log`](references/crash-worker-exit-log.md) - Extract Crash Context from Worker Exit Log Messages
- [`crash-error-page-redirect`](references/crash-error-page-redirect.md) - Avoid Crashes from error_page Internal Redirect Context Invalidation

### 2. Memory Bug Detection (CRITICAL)

- [`memdbg-use-after-free`](references/memdbg-use-after-free.md) - Detect Use-After-Free from Pool Destruction Timing
- [`memdbg-pool-leak-pattern`](references/memdbg-pool-leak-pattern.md) - Identify Pool Memory Leak Patterns from Growing Worker RSS
- [`memdbg-slab-corruption`](references/memdbg-slab-corruption.md) - Diagnose Shared Memory Slab Corruption from Multi-Worker Crashes
- [`memdbg-cleanup-handler-leak`](references/memdbg-cleanup-handler-leak.md) - Detect Resource Leaks from Missing Pool Cleanup Handlers
- [`memdbg-buffer-overrun`](references/memdbg-buffer-overrun.md) - Find Buffer Overrun from ngx_pnalloc Size Miscalculation
- [`memdbg-temp-pool-misuse`](references/memdbg-temp-pool-misuse.md) - Avoid Storing Long-Lived Pointers in Temporary Pools
- [`memdbg-valgrind-pool-trace`](references/memdbg-valgrind-pool-trace.md) - Use Valgrind Pool-Level Tracing to Find Leaked Allocations

### 3. GDB & Core Dump Analysis (HIGH)

- [`gdb-coredump-setup`](references/gdb-coredump-setup.md) - Configure Core Dump Generation for nginx Worker Crashes
- [`gdb-attach-worker`](references/gdb-attach-worker.md) - Attach GDB to a Running nginx Worker Process
- [`gdb-backtrace-read`](references/gdb-backtrace-read.md) - Read nginx Backtrace to Identify Crash Module and Phase
- [`gdb-inspect-request`](references/gdb-inspect-request.md) - Inspect ngx_http_request_t Fields in GDB for Request State
- [`gdb-memory-buffer-extract`](references/gdb-memory-buffer-extract.md) - Extract Debug Log from Memory Buffer Using GDB Script
- [`gdb-watchpoint-corruption`](references/gdb-watchpoint-corruption.md) - Use GDB Watchpoints to Catch Memory Corruption at Write Time

### 4. Request Flow Tracing (HIGH)

- [`trace-phase-handler-flow`](references/trace-phase-handler-flow.md) - Trace Request Through HTTP Phase Handlers
- [`trace-subrequest-tree`](references/trace-subrequest-tree.md) - Map Subrequest Parent-Child Relationships for Debugging
- [`trace-filter-chain-order`](references/trace-filter-chain-order.md) - Trace Filter Chain Execution Order and Data Flow
- [`trace-upstream-callback-seq`](references/trace-upstream-callback-seq.md) - Trace Upstream Callback Sequence for Proxy Debugging
- [`trace-event-handler-chain`](references/trace-event-handler-chain.md) - Trace Event Handler Execution for Connection Debugging
- [`trace-config-inheritance`](references/trace-config-inheritance.md) - Trace Configuration Inheritance Through Server and Location Blocks

### 5. Debug Logging Patterns (MEDIUM-HIGH)

- [`dbglog-debug-mask`](references/dbglog-debug-mask.md) - Use Correct Debug Mask for Targeted Log Filtering
- [`dbglog-debug-connection`](references/dbglog-debug-connection.md) - Use debug_connection to Isolate Single-Client Debug Output
- [`dbglog-memory-buffer`](references/dbglog-memory-buffer.md) - Use Memory Buffer Logging to Capture Debug Output Without Disk I/O
- [`dbglog-log-action-string`](references/dbglog-log-action-string.md) - Set Log Action String for Context in Error Messages
- [`dbglog-format-ngx-str`](references/dbglog-format-ngx-str.md) - Format ngx_str_t Correctly in Debug Log Messages

### 6. State & Lifecycle Debugging (MEDIUM)

- [`state-connection-lifecycle`](references/state-connection-lifecycle.md) - Track Connection State Transitions for Lifecycle Debugging
- [`state-upstream-state-machine`](references/state-upstream-state-machine.md) - Debug Upstream Module State by Logging Transition Points
- [`state-timer-leak`](references/state-timer-leak.md) - Detect Timer Leaks from Events Not Removed Before Pool Destruction
- [`state-event-flag-debug`](references/state-event-flag-debug.md) - Inspect Event Flags to Debug Unexpected Handler Invocation
- [`state-request-count-track`](references/state-request-count-track.md) - Track Request Reference Count to Debug Premature Destruction

### 7. Dynamic Tracing Tools (MEDIUM)

- [`probe-strace-syscall`](references/probe-strace-syscall.md) - Use strace to Trace System Call Patterns in nginx Workers
- [`probe-dtrace-request`](references/probe-dtrace-request.md) - Trace Request Processing with DTrace pid Provider
- [`probe-systemtap-pool`](references/probe-systemtap-pool.md) - Trace Memory Pool Allocations with SystemTap
- [`probe-ebpf-latency`](references/probe-ebpf-latency.md) - Measure Per-Function Latency with eBPF Probes
- [`probe-strace-fd-leak`](references/probe-strace-fd-leak.md) - Detect File Descriptor Leaks with strace and /proc

### 8. Build & Sanitizer Configuration (LOW-MEDIUM)

- [`build-debug-flags`](references/build-debug-flags.md) - Compile nginx with Full Debug Symbols and No Optimization
- [`build-asan-configure`](references/build-asan-configure.md) - Build nginx with AddressSanitizer for Memory Error Detection
- [`build-single-process`](references/build-single-process.md) - Use Single-Process Mode for Simplified Debugging
- [`build-valgrind-suppressions`](references/build-valgrind-suppressions.md) - Use nginx Valgrind Suppressions to Reduce False Positives
- [`build-debug-palloc`](references/build-debug-palloc.md) - Enable NGX_DEBUG_PALLOC for Fine-Grained Pool Allocation Tracking

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
nginx-c-module-perf The nginx-c-module-perf skill guides performance and reliability work on nginx C modules. Use it when tuning buffers, connections, caching, or error handling. CX Codex +1 267installs react-native-elements This skill guides React Native Elements setup, component choices, theming, and list performance. Use it while building or reviewing a React Native app with RNE. CX Codex +1 265installs bug-review bug-review is a Claude Code skill that runs five parallel passes over a PR diff, selects findings by majority vote, then checks them with a separate Opus validator. It finds bugs before the merge. CX Codex +1 264installs effect-ts A skill providing patterns and reference guides for Effect-TS: typed error channels, Effect.gen flows, Layers, and fiber concurrency. CX Codex +1 263installs rust-write-tests rust-write-tests guides coding agents in writing deep Rust tests that target invariants, isolate test files, and systematically eradicate flaky async test runs. CX Codex +1 257installs rails-application-ui-blocks rails-application-ui-blocks is a Claude Code skill that assembles UI blocks in Ruby on Rails ERB views while preserving Turbo, Stimulus, and accessibility hooks. CX Codex +1 257installs rust-implement rust-implement enforces a four-pass discipline for Rust development, moving from strict type design to implementation, simplification, and automated linting. CX Codex +1 254installs domain-architect domain-architect identifies business domains in a Swift codebase by tracing user capabilities, not folder names. Maps each domain's vertical slice from types to UI. CX Codex +1 249installs

Project sponsors

Companies that keep this analytics open