Local Llm Troubleshooter

Diagnose and fix broken local LLM stacks, GPU issues, and stalled model downloads across Ollama, LM Studio, and more.

Install
cmdop skills install agensi-local-llm-troubleshooter

Local LLM Troubleshooter is a diagnostic skill for developers and AI engineers running local inference stacks that are failing or underperforming. It targets Ollama, LM Studio, llama.cpp, vLLM, and Hugging Face hub downloads as supported environments.

The skill runs a bundled diagnostic script, llm_doctor.py, which acts as a system sensor rather than relying on generic advice. It probes connection states, scans logs for known failure signatures, and detects stalled model downloads. Specific technical blockers it can identify include GGUF version mismatches, CUDA out-of-memory errors, port conflicts, runner crashes, and stalled Hugging Face blob downloads.

Findings are mapped to a curated playbook of OS-specific fixes covering Apple Silicon, NVIDIA GPU, and WSL2 environments. The output is a structured triage report that includes a connectivity verdict (up, down, or stuck), identification of the specific bottleneck causing the problem, and an ordered list of high-probability fixes. These fixes can range from context window adjustments to environment variable corrections.

This skill is suited for situations where generic AI advice produces circular responses about local hardware or inference configuration issues. It does not cover cloud-hosted inference services or model training pipelines.

Use cases

  • Identify why an Ollama model fails to load or respond
  • Detect CUDA out-of-memory errors on NVIDIA GPU setups
  • Find port conflicts blocking LM Studio or vLLM inference servers
  • Diagnose stalled Hugging Face model blob downloads
  • Get OS-specific fixes for Apple Silicon inference issues
  • Resolve GGUF version mismatches causing runner crashes

When to use it

  • Local inference server (Ollama, LM Studio, llama.cpp, vLLM) is unresponsive or slow
  • Model downloads from Hugging Face have stalled and won't resume
  • GPU acceleration is not working as expected on NVIDIA or Apple Silicon
  • Log scanning is needed to identify specific failure signatures in local LLM runners
  • Generic troubleshooting advice has not resolved the issue

When not to use it

  • The inference stack is hosted on a cloud provider rather than running locally
  • The issue involves model training rather than local inference serving
  • The environment is not one of the supported platforms: Ollama, LM Studio, llama.cpp, vLLM, or Hugging Face
  • No environment variables or configuration are available to the diagnostic script