Proxmox troubleshooting methodology

Why this matters in production

“Random restart until it works” is the most common troubleshooting anti-pattern. It masks the underlying issue, causes data loss, and trains operators badly.

The methodology

flowchart LR
  A[Symptom reported] --> B[Reproducible?]
  B -->|no| C[Wait; collect more data]
  B -->|yes| D[Recent changes?]
  D --> E[Inspect relevant subsystem]
  E --> F[Identify root cause]
  F --> G[Apply targeted fix]
  G --> H[Verify]
  H --> I[Document]

Step 1: Is it reproducible?

Some incidents are transient. If you cannot reproduce, gather data before acting.

• Check monitoring for the time of the incident.
• Look for related alerts.
• Ask if anyone changed anything recently.

Step 2: What changed recently?

Most incidents follow a change. Check:

• Recent patches or upgrades.
• Recent configuration changes.
• Recent hardware changes.
• Recent workload changes.

Step 3: Inspect the right subsystem

Step 4: Identify root cause

Distinguish symptom from cause:

• VM is slow → disk I/O slow (cause) → disk is failing (root cause)
• Cluster has no quorum → Corosync partition → switch port down (root cause)

Root cause is what you fix. Symptoms are what you observe.

Step 5: Apply targeted fix

Do not change multiple things at once. Apply one fix, observe, repeat.

Step 6: Verify

Confirm the fix worked:

• Symptoms resolved.
• No new symptoms introduced.
• Monitoring is back to normal.

Step 7: Document

Document for future operators:

• What happened.
• How it was diagnosed.
• What the fix was.
• How to prevent it.

Anti-patterns

Production considerations

Common mistakes

• “Let me just restart it.”
• Skipping the documentation step.
• Not collecting state before changes.

Key takeaways

• Reproducible? Recent changes? Right subsystem?
• Distinguish symptom from cause.
• Document for the future.

Knowledge check