obsidian-incident-runbook

Troubleshoot Obsidian plugin failures with systematic incident response. Use when plugins crash, data is corrupted, or users report critical issues with your Obsidian plugin. Trigger with phrases like "obsidian crash", "obsidian plugin broken", "obsidian incident", "debug obsidian failure", "obsidian emergency".

Jump to install

Repository: jeremylongshore/tons-of-skills-marketplace
Last source activity: August 19, 2026 at 12:13
Detected SKILL.md language: English
Stars: 2,677
Forks: 392

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	obsidian-incident-runbook
description	Troubleshoot Obsidian plugin failures with systematic incident response. Use when plugins crash, data is corrupted, or users report critical issues with your Obsidian plugin. Trigger with phrases like "obsidian crash", "obsidian plugin broken", "obsidian incident", "debug obsidian failure", "obsidian emergency".
allowed-tools	Read, Grep, Bash(node:*)
version	1.13.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","obsidian","debugging","incident-response"]
compatibility	Designed for Claude Code

Obsidian Incident Runbook

Overview

Systematic procedures for diagnosing and resolving Obsidian failures: plugin crashes, vault corruption, sync conflicts, performance degradation, and broken CSS/themes. Each section is a self-contained runbook -- jump to the relevant one.

Prerequisites

Access to the affected Obsidian vault directory
Developer Console access (Ctrl+Shift+I / Cmd+Option+I)
Terminal access for filesystem operations
Backup awareness (know where your backups are before making changes)

Instructions

Step 1: Quick Triage

Determine the category before diving in:

Symptom	Category	Go to
Obsidian crashes on open or plugin enable	Plugin crash	Step 2
Notes missing, corrupted, or garbled	Vault corruption	Step 3
Duplicate files, conflicting edits	Sync conflicts	Step 4
Obsidian slow, high CPU/memory, lag while typing	Performance	Step 5
UI elements missing, wrong colors, broken layout	CSS/Theme	Step 6

Step 2: Plugin Crash Recovery

Immediate: Enter Safe Mode

If Obsidian crashes on startup, force safe mode:

VAULT_PATH=~/path/to/vault

# Option A: Disable all community plugins
echo '[]' > "$VAULT_PATH/.obsidian/community-plugins.json"

# Option B: Disable a specific suspect plugin
python3 -c "
import json
plugins = json.load(open('$VAULT_PATH/.obsidian/community-plugins.json'))
suspect = 'plugin-id-here'
if suspect in plugins:
    plugins.remove(suspect)
    json.dump(plugins, open('$VAULT_PATH/.obsidian/community-plugins.json', 'w'))
    print(f'Disabled {suspect}')
else:
    print(f'{suspect} not in active plugins')
"

Reopen Obsidian. If it loads, the disabled plugin was the cause.

Diagnose from Console

Open Developer Console (Ctrl+Shift+I) and look for errors:


.(app..).( {
   loaded = app..[id];
   (!loaded) .();
});



.(,  {
  .(, e.);
});

VAULT_PATH=~/path/to/vault
PLUGINS_FILE="$VAULT_PATH/.obsidian/community-plugins.json"

# Save original list
cp "$PLUGINS_FILE" "$PLUGINS_FILE.bak"

# Get all plugins
python3 -c "
import json
plugins = json.load(open('$PLUGINS_FILE'))
half = len(plugins) // 2

# Enable only first half
json.dump(plugins[:half], open('$PLUGINS_FILE', 'w'))
print(f'Enabled {half} of {len(plugins)} plugins: {plugins[:half]}')
print(f'Disabled: {plugins[half:]}')
print('Open Obsidian. If it crashes, problem is in first half. If stable, second half.')
"

VAULT_PATH=~/path/to/vault

# Find files with null bytes (corruption indicator)
echo "=== Files with null bytes ==="
find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -exec grep -Pl '\x00' {} \;

# Find zero-byte files (likely lost content)
echo "=== Empty files ==="
find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -empty

# Find files with broken YAML frontmatter
echo "=== Broken frontmatter ==="
for f in "$VAULT_PATH"/*.md "$VAULT_PATH"/**/*.md; do
  [ -f "$f" ] || continue
  if head -1 "$f" | grep -q '^---' && ! awk '/^---/{c++; if(c==2) exit 0} END{exit (c<2)}' "$f"; then
    echo "  Unclosed frontmatter: $f"
  fi
done

# List recently deleted files
ls -lt "$VAULT_PATH/.trash/" 2>/dev/null | head -20

# Restore a specific file
cp "$VAULT_PATH/.trash/important-note.md" "$VAULT_PATH/recovered/"

cd "$VAULT_PATH"

# See what changed recently
git log --oneline -20
git diff HEAD~1 --stat

# Restore a specific file to its last good state
git checkout HEAD~1 -- "path/to/corrupted-note.md"

# Restore the entire vault to last commit (DESTRUCTIVE -- stash first)
git stash
git checkout HEAD -- .

# macOS Time Machine
tmutil listbackups 2>/dev/null | tail -5
# Then browse: /Volumes/TimeMachine/Backups.backupdb/.../path/to/vault

# Linux (btrfs snapshots)
ls /.snapshots/ 2>/dev/null

VAULT_PATH=~/path/to/vault

# Find all conflict files
echo "=== Sync Conflicts ==="
find "$VAULT_PATH" -name '*conflict*' -not -path '*/.obsidian/*'

# Compare a conflict with its original
ORIGINAL="$VAULT_PATH/Meeting Notes.md"
CONFLICT=$(find "$VAULT_PATH" -name "Meeting Notes*conflict*" | head -1)
if [ -n "$CONFLICT" ]; then
  diff "$ORIGINAL" "$CONFLICT"
fi

cd "$VAULT_PATH"

# Check for merge conflicts
git status | grep 'both modified'

# For each conflicted file, resolve the conflict markers
# <<<<<<< HEAD
# (your changes)
# =======
# (their changes)
# >>>>>>> branch
grep -rl '<<<<<<< ' "$VAULT_PATH"/*.md 2>/dev/null

// Paste in Developer Console

// Check memory usage
console.log('Memory:', JSON.stringify(performance.memory, null, 2));

// Time plugin load
Object.entries(app.plugins.plugins).forEach(([id, plugin]) => {
  const start = performance.now();
  // Plugins are already loaded, but check their event listener count
  const events = plugin._events?.length || 0;
  console.log(`${id}: ${events} event listeners`);
});

// Check for expensive metadata cache operations
console.time('metadataCache');
const allFiles = app.vault.getMarkdownFiles();
allFiles.forEach(f => app.metadataCache.getFileCache(f));
console.timeEnd('metadataCache');
console.log(`Files scanned: ${allFiles.length}`);

VAULT_PATH=~/path/to/vault
PLUGINS_FILE="$VAULT_PATH/.obsidian/community-plugins.json"

# Save original
cp "$PLUGINS_FILE" "$PLUGINS_FILE.bak"

# Get plugin list
python3 -c "
import json
plugins = json.load(open('$PLUGINS_FILE'))
print('Current plugins:')
for i, p in enumerate(plugins):
    print(f'  {i}: {p}')
print(f'\nTotal: {len(plugins)} plugins')
print('\nTo disable one at a time:')
for p in plugins:
    without = [x for x in plugins if x != p]
    print(f'  Without {p}: {len(without)} remaining')
"

VAULT_PATH=~/path/to/vault

# Disable all CSS snippets
python3 -c "
import json
try:
    a = json.load(open('$VAULT_PATH/.obsidian/appearance.json'))
    a['enabledCssSnippets'] = []
    a['cssTheme'] = ''  # Reset to default theme
    json.dump(a, open('$VAULT_PATH/.obsidian/appearance.json', 'w'), indent=2)
    print('Reset theme and disabled all snippets')
except Exception as e:
    print(f'Error: {e}')
"

VAULT_PATH=~/path/to/vault

# Find snippets with aggressive selectors
for snippet in "$VAULT_PATH/.obsidian/snippets"/*.css; do
  [ -f "$snippet" ] || continue
  name=$(basename "$snippet")
  important_count=$(grep -c '!important' "$snippet" 2>/dev/null)
  if [ "$important_count" -gt 0 ]; then
    echo "$name: $important_count !important declarations"
  fi
done

# Check theme compatibility with current Obsidian version
THEME_DIR="$VAULT_PATH/.obsidian/themes"
for theme in "$THEME_DIR"/*/manifest.json; do
  [ -f "$theme" ] || continue
  python3 -c "
import json
m = json.load(open('$theme'))
print(f\"{m.get('name')}: minAppVersion={m.get('minAppVersion', 'unspecified')}\")
"
done

// Find which CSS rule is affecting a specific element
// Right-click the broken element -> Inspect
// In the Elements panel, check Computed styles and look for overrides

// Programmatically check for theme variable conflicts
const root = getComputedStyle(document.body);
const vars = [
  '--background-primary', '--background-secondary',
  '--text-normal', '--text-accent',
  '--interactive-accent', '--interactive-hover'
];
vars.forEach(v => console.log(`${v}: ${root.getPropertyValue(v)}`));

Issue	Cause	Quick Fix
Console won't open (Obsidian crashes immediately)	Plugin error in `onload()`	Disable all plugins via filesystem (Step 2)
Can't access vault directory	Filesystem permissions	`chmod -R u+rw "$VAULT_PATH"`
Plugin won't disable via `community-plugins.json`	File locked by sync	Stop sync service, edit file, restart
Obsidian hangs (not crashing, just frozen)	Infinite loop in plugin	Force-quit (kill process), then disable suspect plugin
Safe mode still crashes	Core Obsidian issue, not plugins	Reinstall Obsidian; vault data is separate from app
Recovery file also corrupted	Filesystem-level issue	Check disk health (`fsck`, `diskutil`, `chkdsk`)