debug-hang

Diagnose distributed training hangs in Ray clusters by analyzing call stacks and task states.

566|137|Updated Apr 13, 2026
One-click install
npx skills add https://github.com/redai-infra/Relax --skill debug-hang
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-hang
Source: https://github.com/redai-infra/Relax/tree/main/skills/debug-hang
Command: npx skills add https://github.com/redai-infra/Relax --skill debug-hang

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

This Skill helps users automatically diagnose and troubleshoot issues causing training tasks to hang in distributed Ray environments, reducing downtime and manual effort.

Core Features & Use Cases

  • Cluster Status Monitoring: Checks the health and resource usage of Ray clusters to identify potential bottlenecks.
  • Task and Actor Inspection: Lists running tasks and actors, providing insights into their states and resource assignments.
  • Stack Trace Collection: Gathers call stacks from processes to pinpoint blocking code paths and thread states.
  • Root Cause Analysis: Analyzes dependency chains and common hang patterns to identify root causes like deadlocks, resource starvation, or misconfigurations.
  • Use Case: When a training job stalls unexpectedly, users can run this Skill to gather comprehensive diagnostics and pinpoint the root of the issue.

Quick Start

Run the provided diagnosis script with your Ray cluster address to automatically gather and analyze cluster diagnostics.

Frequently Asked Questions about debug-hang

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

FAQPage Schema
How do I diagnose a distributed training hang in a Ray cluster?

To diagnose a distributed training hang, you can run the diagnosis script with your Ray cluster address to collect task states, monitor resource usage, and analyze blocking call stacks.

What causes distributed training jobs to stall or hang unexpectedly?

Distributed training hangs are caused by deadlocks, resource contention, resource starvation, or misconfigurations, requiring cluster health monitoring and stack trace analysis to pinpoint.

How do I check Ray cluster health and resource usage for bottlenecked tasks?

Checking Ray cluster health involves monitoring resource assignments and listing running tasks and actors to identify potential bottlenecks causing training jobs to stall.

Can I identify deadlocks in distributed training by collecting stack traces?

Yes, collecting call stacks gathers thread states and blocking code paths from processes, enabling root cause analysis to identify deadlocks and resource starvation efficiently.

Does this diagnostics tool require any specific dependencies or setup to run?

No dependencies are required, but you need a running Ray cluster address to execute the provided diagnosis script for automated detection of distributed training issues.

What is the best way to troubleshoot resource contention in Ray distributed training?

Troubleshooting resource contention involves inspecting task and actor states, analyzing dependency chains, and monitoring cluster health to resolve misconfigurations causing job stalls.