Troubleshooting

When the user describes a symptom, error message, or unexpected behavior.

1. Ask for the exact error message (or have the user run docker compose logs api --tail 50)
2. Load ${CLAUDE_PLUGIN_ROOT}/references/common-errors.md and check for a known match
3. If the error involves a model provider, also load ${CLAUDE_PLUGIN_ROOT}/references/api-errors.md
4. If the error involves file uploads or RAG, also load ${CLAUDE_PLUGIN_ROOT}/references/rag-troubleshooting.md
5. Walk through diagnostic steps to confirm root cause
6. Provide exact fix with verification command

Mode 2: Health Check

When the user wants to verify everything is working, or after a deployment/upgrade.

1. Load ${CLAUDE_PLUGIN_ROOT}/references/health-check-script.md for the full procedure
2. Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/check_health.py if the user wants an automated check
3. Walk through each service: Docker containers, API, MongoDB, model endpoints, RAG pipeline, MeiliSearch
4. Report status of each component with exact fix for anything failing

Mode 3: Performance Investigation

When responses are slow, memory is high, or containers keep restarting.

1. Check container resource usage: docker stats --no-stream
2. Check for restart loops: docker compose ps (look at STATUS column for "Restarting")
3. Load ${CLAUDE_PLUGIN_ROOT}/references/docker-diagnostics.md for detailed diagnostic commands
4. Check API response times in logs: docker compose logs api --tail 100 | grep -i "response\|latency\|timeout"
5. Identify bottleneck (API, database, embeddings, external provider) and provide targeted fix

Which mode to use:

• User says "error", "broken", "not working", "fails", "500", "400" → Mode 1
• User says "health check", "verify", "is everything working", "just deployed" → Mode 2
• User says "slow", "high memory", "keeps restarting", "timeout", "performance" → Mode 3

Reference Docs

Load these on demand — only when the topic comes up:

Scripts

Automated diagnostic tools — run when manual checks would be slow:

Proactive Triggers

Surface these WITHOUT being asked when you notice them:

1. Container restarting repeatedly → "Run docker compose logs api --tail 50 — look for OOM kills or missing env vars. If the STATUS column shows 'Restarting', the container is crash-looping. Check the last few log lines before each restart for the root cause."

2. "400 Invalid request format" on agent file upload → "This is a known issue in LibreChat v0.8.3. File uploads to agents via the standard upload button fail with a 400 error. Workaround: Use 'Upload as Text' (the context capability) instead of standard file upload. This extracts file content as text in the system prompt and works reliably."

3. RAG 401 error → "Verify your embeddings provider API key is set correctly in .env. Check that RAG_OPENAI_API_KEY or EMBEDDINGS_PROVIDER and its corresponding key match. Run: docker compose exec rag-api env | grep -i embed to confirm the container received the key."

4. Model returns empty or garbled response → "Check the model name format — it must exactly match the provider's expected format (e.g., mistral-large-latest not mistral-large). Also check dropParams in your endpoint config — some providers reject parameters like stop or stream. Add problematic params to dropParams: [\"stop\"] in librechat.yaml."

Output Format

Diagnostic output should follow this step-by-step format:

**Diagnosis: [Error Name]**

**Step 1: Check [thing]**
Run: `exact command`
Expected: [what good output looks like]
If different: [what it means and next step]

**Step 2: [next check]**
Run: `exact command`
Expected: [what good output looks like]
If different: [what it means and next step]

**Fix:**
[exact commands to fix]

**Verify:**
[command to confirm fix worked]

Example output:

Diagnosis: API container crash loop

Step 1: Check container status Run: docker compose ps Expected: All containers show "Up" with no "Restarting" If different: Note which container is restarting and proceed to Step 2

Step 2: Check recent logs Run: docker compose logs api --tail 30 Expected: No errors in output If different: Look for "FATAL", "Error", or "OOM" messages

Step 3: Check environment variables Run: docker compose exec api env | grep -c "KEY" Expected: At least 1 (your API keys are loaded) If different: Your .env file is not being read — check that it exists alongside docker-compose.yml

Fix:

# If missing .env:
cp .env.example .env
# Edit .env with your API keys, then:
docker compose down && docker compose up -d

Verify:

docker compose ps   # all containers "Up"
curl -s http://localhost:3080/api/health | head -1   # should return OK/JSON

When to Use This Skill vs Others

• troubleshooting vs monitoring: Something is broken right now and needs reactive diagnosis → use troubleshooting. Setting up ongoing observability, log aggregation, or cost tracking → use monitoring (in librechat-ops plugin).
• troubleshooting vs [any skill]: If something is broken (errors, crashes, failures), start with troubleshooting. If something needs to be configured (setup, change, enable), use the domain-specific skill instead.

Related Skills

Same plugin (librechat-core):

• config: For YAML configuration changes (endpoints, modelSpecs, interface). NOT for diagnosing errors — if config changes broke something, start here then use config to fix.
• agents: For agent prompt design, capabilities, and sharing. NOT for agent errors — diagnose here first, then use agents to reconfigure.

Other plugins (install separately):

• monitoring (librechat-ops): For setting up logging, Langfuse, and cost tracking. Install: /plugin install librechat-ops@librechat-skills
• deployment (librechat-ops): For Docker Compose and infrastructure setup. Install: /plugin install librechat-ops@librechat-skills
• rag (librechat-data): For setting up the RAG pipeline (not just fixing it). Install: /plugin install librechat-data@librechat-skills