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
echo '[]' > "$VAULT_PATH/.obsidian/community-plugins.json"
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:
Object.entries(app.plugins.manifests).forEach(([id, manifest]) => {
const loaded = app.plugins.plugins[id];
if (!loaded) console.error(`FAILED TO LOAD: ${id} v${manifest.version}`);
});
window.addEventListener('unhandledrejection', (e) => {
console.error('Unhandled rejection:', e.reason);
});
Binary search for the offending plugin
If multiple plugins could be the cause:
VAULT_PATH=~/path/to/vault
PLUGINS_FILE="$VAULT_PATH/.obsidian/community-plugins.json"
cp "$PLUGINS_FILE" "$PLUGINS_FILE.bak"
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.')
"
Repeat halving until you isolate the single offending plugin.
Step 3: Vault Corruption Recovery
Check for corrupted files
VAULT_PATH=~/path/to/vault
echo "=== Files with null bytes ==="
find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -exec grep -Pl '\x00' {} \;
echo "=== Empty files ==="
find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -empty
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
Recover from .trash
Obsidian moves deleted files to .trash/ in the vault:
ls -lt "$VAULT_PATH/.trash/" 2>/dev/null | head -20
cp "$VAULT_PATH/.trash/important-note.md" "$VAULT_PATH/recovered/"
Recover from Git backup
If the vault is under Git version control:
cd "$VAULT_PATH"
git log --oneline -20
git diff HEAD~1 --stat
git checkout HEAD~1 -- "path/to/corrupted-note.md"
git stash
git checkout HEAD -- .
Recover from filesystem snapshots
tmutil listbackups 2>/dev/null | tail -5
ls /.snapshots/ 2>/dev/null
Step 4: Sync Conflict Resolution
Obsidian Sync conflicts
Obsidian Sync creates conflict files named Note (conflict YYYY-MM-DD).md:
VAULT_PATH=~/path/to/vault
echo "=== Sync Conflicts ==="
find "$VAULT_PATH" -name '*conflict*' -not -path '*/.obsidian/*'
ORIGINAL="$VAULT_PATH/Meeting Notes.md"
CONFLICT=$(find "$VAULT_PATH" -name "Meeting Notes*conflict*" | head -1)
if [ -n "$CONFLICT" ]; then
diff "$ORIGINAL" "$CONFLICT"
fi
Resolution: Open both files in Obsidian, manually merge content into the original, delete the conflict file.
Git sync conflicts
cd "$VAULT_PATH"
git status | grep 'both modified'
grep -rl '<<<<<<< ' "$VAULT_PATH"/*.md 2>/dev/null
Prevent future conflicts
In .obsidian/sync.json or your Git workflow:
- Exclude
workspace.json and workspace-mobile.json from sync (per-device files)
- Avoid editing the same note on two devices simultaneously
- For Git: commit and push frequently; pull before editing
Step 5: Performance Degradation
Diagnose the bottleneck
console.log('Memory:', JSON.stringify(performance.memory, null, 2));
Object.entries(app.plugins.plugins).forEach(([id, plugin]) => {
const start = performance.now();
const events = plugin._events?.length || 0;
console.log(`${id}: ${events} event listeners`);
});
console.time('metadataCache');
const allFiles = app.vault.getMarkdownFiles();
allFiles.forEach(f => app.metadataCache.getFileCache(f));
console.timeEnd('metadataCache');
console.log(`Files scanned: ${allFiles.length}`);
Disable plugins one by one
Systematic approach to find the performance culprit:
VAULT_PATH=~/path/to/vault
PLUGINS_FILE="$VAULT_PATH/.obsidian/community-plugins.json"
cp "$PLUGINS_FILE" "$PLUGINS_FILE.bak"
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')
"
Then for each suspect:
- Remove it from
community-plugins.json
- Restart Obsidian
- Test performance
- If improved, that plugin is the bottleneck
- If unchanged, restore it and try the next
Common performance fixes
- Vault with 10,000+ files: disable Dataview's automatic refresh, use lazy loading
- Many backlinks: disable backlinks panel or set it to collapsed by default
- Large files (1MB+): split into smaller notes using note refactoring
- Too many plugins (20+): audit and remove unused plugins
Step 6: CSS and Theme Issues
Nuclear option: Reset all custom CSS
VAULT_PATH=~/path/to/vault
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}')
"
Restart Obsidian. If the UI is fixed, re-enable snippets and theme one at a time.
Check for CSS conflicts
VAULT_PATH=~/path/to/vault
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
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
Diagnose specific CSS problems
In Developer Console:
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)}`));
Output
- Identified root cause of the incident
- Applied fix (plugin disabled, file recovered, conflict resolved, CSS reset)
- Documented what happened for future reference
- Preventive measures configured (backups, sync exclusions, performance monitoring)
Error Handling
| 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) |
Examples
Plugin crash on startup: User reports Obsidian instantly closes after opening a vault. Enter safe mode by clearing community-plugins.json (Step 2). Reopen works. Binary search reveals obsidian-excalidraw conflicts with a newly installed obsidian-kanban. Disable one, report the conflict to both plugin authors.
Missing notes after sync: User opens vault on laptop, 20 notes are gone. Check .trash/ -- empty. Check Git log -- notes were deleted in a commit from their phone. git checkout HEAD~3 -- missing-folder/ restores them. Add the folder to selective sync to prevent mobile edits.
Slow vault with 8,000 notes: Obsidian takes 15 seconds to open and typing lags. Developer Console shows metadataCache taking 4 seconds. Disabling Dataview drops it to 1 second. Solution: configure Dataview to use manual refresh instead of auto-refresh, and add dv.pages limits to expensive queries.
Resources
Next Steps
For collecting detailed diagnostics to share with plugin developers, see obsidian-debug-bundle. For data backup and recovery strategies, see obsidian-data-handling.
