Skills backend-hang-debug

📦

backend-hang-debug

Name: backend-hang-debug
Author: BenderFendor

Content revision r2 Safe ⚙️ External commands🌐 Network access📁 Filesystem access

Diagnose FastAPI Backend Hangs

FastAPI streams can freeze the event loop during executor shutdown. This skill guides stack capture, executor cleanup, and responsiveness checks.

Supports: Claude Codex Code(CC)

🥉 79 Bronze

Install with my Agent

Copy this request to your Agent. It includes the canonical Skill page and manifest.

Agent request

Review the Skillstore skill "backend-hang-debug" from https://skillstore.io/skills/benderfendor-backend-hang-debug.md and its manifest at https://skillstore.io/api/skills/benderfendor-backend-hang-debug/manifest. Verify the artifact. You may proceed after verification, subject to the environment's own policy.

Your Agent should still show its plan and request any confirmation required by the security policy.

Agent-readable resources

Use these links when an AI agent, crawler, or script needs clean context instead of reading the full page.

Markdown detail GET /skills/benderfendor-backend-hang-debug.md Signed manifest GET /api/skills/benderfendor-backend-hang-debug/manifest Signed lockfile GET /api/skills/benderfendor-backend-hang-debug/lockfile

Test it

Using "backend-hang-debug". The health endpoint times out after a client disconnects from the news stream.

Expected outcome:

The listener is active, so startup failure is unlikely.
Capture the main process stack and look for executor shutdown on the event-loop thread.
Cancel pending futures and use non-blocking shutdown during stream cleanup.

Using "backend-hang-debug". The stack dump shows ThreadPoolExecutor shutdown waiting below the stream generator.

Expected outcome:

The event loop is waiting for worker completion during generator cleanup.
Move executor creation outside the synchronous context manager.
Retest health requests before, during, and after aborting the stream.

Security Audit

Safe

v9 • 7/23/2026 Open versioned report

The audit confirms one high-severity risk: line 19 instructs users to run a process profiler with sudo from a host-specific path. The other 39 findings are false positives caused by Markdown code spans or scoped local diagnostics with fixed arguments and loopback URLs. No prompt injection, exfiltration intent, or other semantic threat was found.

Files scanned

Lines analyzed

Review items

False positives ignored

Capability review items (1)

These are real local capabilities that may be expected for this skill, so they require review but are not counted as confirmed malicious behavior.

High

SKILL.md:19

sudo privilege escalation

3. **Stack capture** (inside backend venv): `uv pip install py-spy` then `sudo /home/bender/classwor

The skill explicitly instructs users to run py-spy with sudo, granting a profiler root-level process attachment capability. The command also uses a host-specific executable path without a least-privilege alternative.

Risk Factors

⚙️ External commands (28)

🌐 Network access (7)

SKILL.md:34 SKILL.md:43 SKILL.md:9 SKILL.md:17 SKILL.md:36 SKILL.md:41 SKILL.md:42

📁 Filesystem access (2)

SKILL.md:19 SKILL.md:18

Audited by: codex View Audit History →

Share & cite this report

Share the versioned assessment report, neutral badge, embed card, and citations. Skillstore reports evidence without deciding whether this Skill is safe.

Open versioned report

Copy report link

https://skillstore.io/skills/benderfendor-backend-hang-debug/audits/9?utm_source=security_passport&utm_medium=share&utm_campaign=versioned_report

Markdown badge

[![Skillstore security assessment](https://skillstore.io/badges/skills/benderfendor-backend-hang-debug/security.svg)](https://skillstore.io/skills/benderfendor-backend-hang-debug?utm_source=security_passport_badge)

HTML badge

<a href="https://skillstore.io/skills/benderfendor-backend-hang-debug?utm_source=security_passport_badge"><img src="https://skillstore.io/badges/skills/benderfendor-backend-hang-debug/security.svg" alt="Skillstore security assessment" loading="lazy"></a>

Embed card

<iframe src="https://skillstore.io/embed/skills/benderfendor-backend-hang-debug.html" title="Skillstore Security Assessment" sandbox="allow-popups allow-popups-to-escape-sandbox" loading="lazy" referrerpolicy="no-referrer" width="420" height="180"></iframe>

Academic citations (APA · BibTeX · CFF)

APA citation

BenderFendor. (2026). backend-hang-debug security audit report (audit version 9) [Author version unspecified]. Skillstore. https://skillstore.io/skills/benderfendor-backend-hang-debug/audits/9

BibTeX citation

@techreport{benderfendor-benderfendor-backend-hang-debug-2026,
  author = {BenderFendor},
  title = {backend-hang-debug security audit report (audit version 9)},
  institution = {Skillstore},
  year = {2026},
  number = {9},
  url = {https://skillstore.io/skills/benderfendor-backend-hang-debug/audits/9},
  note = {Author version unspecified}
}

CITATION.cff

cff-version: 1.2.0
message: "If you use this Skill, cite its author and this versioned security audit report."
title: "backend-hang-debug security audit report (audit version 9)"
version: "unspecified"
type: report
authors:
  - name: "BenderFendor"
date-released: "2026-07-23"
url: "https://skillstore.io/skills/benderfendor-backend-hang-debug/audits/9"
identifiers:
  - type: other
    value: "skillstore:benderfendor-backend-hang-debug:audit:9"
    description: "Skillstore immutable audit report identifier"

Skillstore Score

Why this score Evidence Confidence: High

Architecture

Maintainability

Content

Community

Spec Compliance

What You Can Build

Restore a stalled development server

Check whether a local FastAPI listener responds and identify blocking executor shutdown frames.

Investigate stream disconnect failures

Trace why aborting an SSE client freezes later requests and review executor cleanup behavior.

Review concurrency fixes

Evaluate cancellation, shutdown, and timeout choices before deploying a streaming backend change.

Try These Prompts

Check endpoint responsiveness

Help me confirm whether my FastAPI health endpoint hangs. Use timeout-based localhost checks and explain each observation before suggesting changes.

Review a stream freeze

Diagnose an SSE disconnect freeze. Review my stream handler and identify any ThreadPoolExecutor shutdown that can block the event loop.

Interpret live stacks

Interpret this py-spy stack dump from a FastAPI process. Trace blocking frames and distinguish event-loop stalls from slow worker I/O.

Design executor cleanup

Design a non-blocking executor lifecycle for this FastAPI stream. Include cancellation, shutdown behavior, failure modes, and a focused verification plan.

Best Practices

Use bounded localhost checks before changing code.
Capture evidence from the correct process before diagnosing the cause.
Verify responsiveness during normal completion and client disconnects.

Avoid

Do not run privileged profilers without explicit approval.
Do not treat every slow RSS request as an event-loop failure.
Do not use blocking executor shutdown inside asynchronous cleanup.

Frequently Asked Questions

What problem does this skill diagnose?

It focuses on FastAPI event-loop hangs caused by waiting for ThreadPoolExecutor workers during stream cleanup.

Does it support production systems?

The workflow can inform production diagnosis, but access controls, monitoring, and change procedures still apply.

Why use py-spy?

py-spy captures live Python stacks and can reveal whether the event loop waits inside executor shutdown.

Is sudo always required?

No. Prefer least-privilege ptrace configuration, and use elevated access only with explicit authorization.

Does non-blocking shutdown stop running threads?

No. It avoids waiting for completion, while cancellation mainly affects work that has not started.

How is the fix verified?

Repeat health checks, abort a stream client, confirm later requests respond, and inspect stacks for blocking shutdown frames.

Developer Details

Author

BenderFendor

License

MIT

Skillstore revision

Version notice

The author did not declare a version.

Repository

https://github.com/BenderFendor/Thesis/tree/main/.github/skills/backend-hang-debug

Ref

8c3e20bba512c392d9b02ee748b18e0b09d4982c

Maintenance freshness

7/24/2026

Usage

6 downloads · 286 views

File structure

📄 SKILL.md