troubleshooting

Diagnose root causes of command failures, hangs, and Docker container issues.

Updated Aug 1, 2026
One-click install
npx skills add https://github.com/siegenthalerroger/.llmctl-marketplace --skill troubleshooting-siegenthalerroger
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: troubleshooting
Source: https://github.com/siegenthalerroger/.llmctl-marketplace/tree/main/plugins/llmctl-core-0.4.0/skills/troubleshooting
Command: npx skills add https://github.com/siegenthalerroger/.llmctl-marketplace --skill troubleshooting-siegenthalerroger

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When commands fail, hang, or behave unexpectedly, guessing at fixes wastes time and often makes things worse. This Skill enforces a disciplined diagnosis-first workflow so root causes are found before any configuration is changed. ## Core Features & Use Cases - Root-Cause Diagnosis: Reads child logs behind orchestrator failures (helm hooks, controller events), uses logs --previous for crashed containers, and locates the real Caused by: instead of acting on wrapper summaries. - Version & Capability Verification: Pins actual deployed versions before version-dependent reasoning and probes real permissions with kubectl auth can-i or dry-runs instead of trusting context names. - Docker Container Debugging: Avoids -it foreground traps, overrides custom entrypoints, writes multi-line logic to mounted script files, and handles busybox/Alpine tool differences. - Use Case: A helm upgrade fails with "hook failed / Job not ready". Instead of retrying blindly, the Skill reads the failed Job's pod logs, finds the database migration error, cleans up the stuck release state, and re-runs the upgrade. ## Quick Start Diagnose why my helm upgrade is failing and find the root cause before changing any configuration.

Frequently Asked Questions about troubleshooting

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

FAQPage Schema
How do I find the root cause of a failed helm upgrade?▼

Read the logs of the failed child resource, such as the hook Job's pod, rather than the helm wrapper summary. Find the root 'Caused by:' entry, clean up leftover state like a stuck failed release or hook Jobs, then re-run the upgrade.

How do I debug a crashed or restarting container in Kubernetes?▼

Use kubectl logs with the --previous flag to see the log from the container instance that actually failed, since the live log belongs to the new attempt. Combine this with pod events to identify the failing step.

Why does docker run -it break my terminal session?▼

A foreground terminal call with docker run -it leaves the shell inside the container, so subsequent commands resolve against container paths where the host filesystem and Docker daemon are unavailable. Omit -it for one-shot commands or run interactively in a background terminal, and type exit to return to the host.

How do I run a shell script in a Docker image with a custom entrypoint?▼

Override the entrypoint with --entrypoint sh and pass the script path, for example docker run --rm --entrypoint sh -v /workspace:/work image:tag /work/script.sh. Write multi-line logic to a mounted script file instead of passing it via -c to avoid quoting corruption.

Can I trust a kubectl context name to tell my access level?▼

No, context and role names do not reliably indicate permissions. Probe the real capability with kubectl auth can-i <verb> <resource>, a --dry-run, or a harmless write before acting or ruling out an operation.

Why do sed or fold commands behave differently inside Alpine containers?▼

Busybox applets in Alpine are reduced implementations, and host syntax like macOS BSD sed -i '' fails against GNU or busybox sed. Inside Linux containers use sed -i with no backup argument, and switch to awk when a busybox applet misbehaves on piped input.