Troubleshooting Template

Quick Diagnosis

# First commands to run - paste these immediately
command --status
systemctl status service-name
journalctl -u service-name --since "5 min ago" -n 50

Symptom Index

Jump to your symptom:

Symptom: [Describe what user sees]

Quick Check

# One-liner to confirm this symptom
command --check

Decision Tree

Check Result Action

Check A

Pass

Not this issue → try Symptom: [Second Symptom]

Check A

Fail

→ Resolution 1a: [Fix Name]

Check B (if A passed)

Pass

Not this issue → try Symptom: [Third Symptom]

Check B

Fail

→ Resolution 1b: [Fix Name]

Resolution 1a: [Fix Name]

Root Cause: Brief explanation of why this happens.

  • Arch

  • RHEL/Fedora

  • Debian/Ubuntu

sudo pacman -S package
sudo systemctl restart service
sudo dnf install package
sudo systemctl restart service
sudo apt install package
sudo systemctl restart service

Verify fix:

command --verify

Resolution 1b: [Fix Name]

Root Cause: Brief explanation.

# Commands to fix

Symptom: [Second Symptom]

Quick Check

# Diagnostic command

Common Causes

  1. Cause A - Resolution 2a: [Fix Name]

  2. Cause B - Resolution 2b: [Fix Name]

Resolution 2a: [Fix Name]

# Fix commands

Resolution 2b: [Fix Name]

# Fix commands

Symptom: [Third Symptom]

Nuclear Options

These are destructive. Use only when all else fails.

Full Reset

# Complete reset - data may be lost
sudo systemctl stop service
sudo rm -rf /var/lib/service/*
sudo systemctl start service

Reinstall

  • Arch

  • RHEL/Fedora

  • Debian/Ubuntu

sudo pacman -Rns package
sudo pacman -S package
sudo dnf remove package
sudo dnf install package
sudo apt purge package
sudo apt install package

Related