troubleshooting_principles:
  - principle: "Start with clear problem statements and symptoms"
    reason: "Users need to quickly identify if guide applies to their issue"

  - principle: "Use If-Then logic flows for decision trees"
    reason: "Systematic elimination of possible causes"

  - principle: "Organize solutions by likelihood and impact"
    reason: "Try simple/common fixes first, escalate to complex"

  - principle: "Follow logical diagnostic sequence (simple to complex)"
    reason: "Minimize time to resolution"

  - principle: "Include verification steps after each fix"
    reason: "Confirm the issue is actually resolved"

  - principle: "Provide rollback instructions"
    reason: "Allow safe recovery if fix causes new issues"

undefined

[Exact error message or code]

undefined

**Expected Output:** [What you should see]
**If this fails:** Continue to Check 2

undefined

undefined

Start
  │
  ├─ Is [condition A] true?
  │    ├─ YES → Go to Solution A
  │    └─ NO → Continue
  │
  ├─ Is [condition B] true?
  │    ├─ YES → Go to Solution B
  │    └─ NO → Continue
  │
  └─ None of the above → Escalate to Support

[verification command]

[rollback command]

---

undefined

undefined

undefined

[Client] → [Load Balancer] → [App Server] → [Database]
                  ↑
            Test here first

undefined

undefined

┌─ Can you reach the server at all?
│
├─ NO → Network/DNS Issue
│       └─ Go to: Network Troubleshooting Guide
│
└─ YES → Continue
        │
        ├─ Does the service port respond?
        │
        ├─ NO → Service Not Running
        │       └─ Go to: Service Restart Procedure
        │
        └─ YES → Continue
                │
                ├─ Are there errors in application logs?
                │
                ├─ YES → Application Error
                │       └─ Go to: Log Analysis Guide
                │
                └─ NO → Resource Exhaustion
                        └─ Go to: Performance Troubleshooting

---

linux_logs:
  system:
    - /var/log/syslog
    - /var/log/messages
    - journalctl -xe

  application:
    - /var/log/[app-name]/
    - ~/.pm2/logs/
    - docker logs [container]

  web_server:
    nginx:
      - /var/log/nginx/error.log
      - /var/log/nginx/access.log
    apache:
      - /var/log/apache2/error.log
      - /var/log/httpd/error_log

  database:
    postgresql:
      - /var/log/postgresql/
    mysql:
      - /var/log/mysql/error.log

undefined

undefined

undefined

Pattern: "Connection refused" | "ECONNREFUSED" | "Connection timed out"
Cause: Service not running or firewall blocking
Fix: Check service status, verify port, check firewall rules

Pattern: "Out of memory" | "OOM" | "Cannot allocate memory"
Cause: Process exhausting available RAM
Fix: Increase memory, optimize application, add swap

Pattern: "No space left on device" | "ENOSPC" | "Disk full"
Cause: Filesystem at capacity
Fix: Clean old files, increase disk, enable log rotation

Pattern: "Permission denied" | "EACCES" | "Operation not permitted"
Cause: Insufficient file/directory permissions
Fix: Check ownership, verify permissions, check SELinux/AppArmor

Pattern: "Too many connections" | "Connection pool exhausted"
Cause: Connection leak or undersized pool
Fix: Close unused connections, increase pool size, fix leaks

---

undefined

#!/bin/bash

undefined

API Not Responding
       │
       ├─ Can you ping the server?
       │   ├─ NO → Check network/DNS
       │   └─ YES ↓
       │
       ├─ Is the service running?
       │   ├─ NO → Start/restart service
       │   └─ YES ↓
       │
       ├─ Is the port listening?
       │   ├─ NO → Check service configuration
       │   └─ YES ↓
       │
       ├─ Does health check pass?
       │   ├─ NO → Check dependencies (DB, cache)
       │   └─ YES ↓
       │
       └─ Check application logs for errors

undefined

undefined

undefined

undefined

undefined

undefined

-- PostgreSQL
SELECT count(*) FROM pg_stat_activity;
SELECT max_connections FROM pg_settings WHERE name = 'max_connections';

-- MySQL
SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

undefined

undefined

-- PostgreSQL: Kill idle connections older than 10 minutes
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle'
  AND state_change < NOW() - INTERVAL '10 minutes';

-- PostgreSQL (requires restart)
ALTER SYSTEM SET max_connections = 200;

-- MySQL (can be done live)
SET GLOBAL max_connections = 200;

---

undefined

---