Obsidian Debug Bundle
Current State
!node --version 2>/dev/null || echo 'N/A'
!python3 --version 2>/dev/null || echo 'N/A'
!uname -a
Overview
Collect comprehensive diagnostics from an Obsidian vault: app version, installed plugins, active theme, vault stats, console errors, and CSS conflicts. Package everything into a markdown debug report.
Prerequisites
- Access to the Obsidian vault's filesystem (the vault directory)
- Terminal access to run collection commands
- Developer Console access in Obsidian (Ctrl+Shift+I / Cmd+Option+I)
Instructions
Step 1: Identify the Vault Path
Obsidian stores vault data in the vault root under .obsidian/. Locate it:
VAULT_PATH=~/Documents/MyVault
VAULT_PATH=~/Obsidian/MyVault
VAULT_PATH="/c/Users/$USER/Documents/MyVault"
ls "$VAULT_PATH/.obsidian/app.json" && echo "Valid vault" || echo "Not a vault"
Step 2: Collect Obsidian Version and App Settings
cat "$VAULT_PATH/.obsidian/app.json" 2>/dev/null | python3 -m json.tool
mdls -name kMDItemVersion /Applications/Obsidian.app 2>/dev/null
snap info obsidian 2>/dev/null | grep installed
Step 3: List Installed Plugins and Their Versions
echo "=== Active Plugins ==="
cat "$VAULT_PATH/.obsidian/community-plugins.json" 2>/dev/null | python3 -m json.tool
echo "=== Plugin Manifests ==="
for dir in "$VAULT_PATH/.obsidian/plugins"/*/; do
if [ -f "$dir/manifest.json" ]; then
echo "--- $(basename "$dir") ---"
python3 -c "
import json
m = json.load(open('$dir/manifest.json'))
print(f\" version: {m.get('version', 'unknown')}\")
print(f\" minAppVersion: {m.get('minAppVersion', 'unknown')}\")
print(f\" author: {m.get('author', 'unknown')}\")
"
fi
done
Step 4: Collect Theme and Appearance Info
echo "=== Appearance ==="
cat "$VAULT_PATH/.obsidian/appearance.json" 2>/dev/null | python3 -m json.tool
echo "=== CSS Snippets ==="
ls "$VAULT_PATH/.obsidian/snippets/" 2>/dev/null || echo "No snippets directory"
THEME=$(python3 -c "
import json
try:
a = json.load(open('$VAULT_PATH/.obsidian/appearance.json'))
print(a.get('cssTheme', 'Default'))
except: print('Default')
")
echo "Active theme: $THEME"
Step 5: Gather Vault Statistics
echo "=== Vault Stats ==="
echo "Markdown files: $(find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -not -path '*/.trash/*' | wc -l)"
echo "Attachments: $(find "$VAULT_PATH" \( -name '*.png' -o -name '*.jpg' -o -name '*.pdf' -o -name '*.mp3' \) -not -path '*/.obsidian/*' | wc -l)"
echo "Total files: $(find "$VAULT_PATH" -type f -not -path '*/.obsidian/*' -not -path '*/.trash/*' | wc -l)"
echo "Vault size: $(du -sh "$VAULT_PATH" 2>/dev/null | cut -f1)"
echo ".obsidian size: $(du -sh "$VAULT_PATH/.obsidian" 2>/dev/null | cut -f1)"
Step 6: Capture Console Errors
Open Obsidian's Developer Console (Ctrl+Shift+I / Cmd+Option+I), then run this in the Console tab to export errors:
(() => {
const errors = [];
const originalError = console.error;
console.error = (...args) => {
errors.push({ time: new Date().toISOString(), message: args.map(String).join(' ') });
originalError.apply(console, args);
};
console.log(`Error capture active. Reproduce your issue, then run:
copy(JSON.stringify(errors, null, 2))`);
})();
Alternatively, check for existing errors:
app.plugins.manifests;
app.plugins.enabledPlugins;
app.plugins.plugins['your-plugin'];
Step 7: Detect CSS Conflicts
for snippet in "$VAULT_PATH/.obsidian/snippets"/*.css; do
[ -f "$snippet" ] || continue
echo "=== $(basename "$snippet") ==="
grep -n 'body\b\|\.app-container\|\.workspace\|\.markdown-preview\|!important' "$snippet" | head -20
done
THEME_DIR="$VAULT_PATH/.obsidian/themes/$THEME"
if [ -d "$THEME_DIR" ]; then
echo "Theme CSS size: $(wc -c < "$THEME_DIR/theme.css" 2>/dev/null) bytes"
fi
Step 8: Generate the Debug Report
Combine all diagnostics into a single markdown note:
REPORT="$VAULT_PATH/debug-report-$(date +%Y%m%d-%H%M%S).md"
cat > "$REPORT" <<'HEADER'
HEADER
cat >> "$REPORT" <<EOF
Generated: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
Platform: $(uname -s) $(uname -m)
Node: $(node --version 2>/dev/null || echo 'N/A')
## App Settings
\`\`\`json
$(cat "$VAULT_PATH/.obsidian/app.json" 2>/dev/null || echo '{}')
\`\`\`
## Active Plugins
\`\`\`json
$(cat "$VAULT_PATH/.obsidian/community-plugins.json" 2>/dev/null || echo '[]')
\`\`\`
## Plugin Versions
$(for dir in "$VAULT_PATH/.obsidian/plugins"/*/; do
[ -f "$dir/manifest.json" ] || continue
name=$(python3 -c "import json; print(json.load(open('$dir/manifest.json')).get('name','?'))" 2>/dev/null)
ver=$(python3 -c "import json; print(json.load(open('$dir/manifest.json')).get('version','?'))" 2>/dev/null)
echo "- $name v$ver"
done)
## Appearance
\`\`\`json
$(cat "$VAULT_PATH/.obsidian/appearance.json" 2>/dev/null || echo '{}')
\`\`\`
## Vault Stats
- Markdown files: $(find "$VAULT_PATH" -name '*.md' -not -path '*/.obsidian/*' -not -path '*/.trash/*' 2>/dev/null | wc -l)
- Total files: $(find "$VAULT_PATH" -type f -not -path '*/.obsidian/*' -not -path '*/.trash/*' 2>/dev/null | wc -l)
- Vault size: $(du -sh "$VAULT_PATH" 2>/dev/null | cut -f1)
## CSS Snippets
$(ls "$VAULT_PATH/.obsidian/snippets/" 2>/dev/null || echo 'None')
## Notes
_Paste console errors below this line after reproducing the issue._
EOF
echo "Debug report written to: $REPORT"
Output
debug-report-YYYYMMDD-HHMMSS.md in the vault root containing:
- Platform and Obsidian version
- Complete plugin list with versions
- Active theme and CSS snippet inventory
- Vault statistics (file count, size)
- Appearance configuration
- Empty section for pasting console errors after reproducing the issue
Error Handling
| Item | Privacy Risk | Action |
|---|
app.json | Contains vault path | Redact path before sharing |
Plugin data.json | May contain API keys | Never include automatically |
| Console logs | May contain file names | Review before sharing |
| Vault path | Personal directory info | Replace with <vault> before sharing |
| CSS snippets | Generally safe | OK to share |
community-plugins.json | Plugin list only | Safe to share |
Examples
Quick bug report: Run Steps 2-5 from terminal, paste output into a GitHub issue. Add console errors from Step 6 if the issue involves runtime failures.
Plugin developer diagnostics: A user reports your plugin crashes. Ask them to run the Step 8 script and share the resulting debug-report-*.md file. Check their Obsidian version against your manifest.json minAppVersion, and look for plugin conflicts in the active plugins list.
CSS debugging: User reports broken styling. Run Step 7 to find !important overrides in snippets. Disable snippets one by one in Settings > Appearance > CSS snippets to isolate the conflict.
Resources
Next Steps
For systematic incident response, see obsidian-incident-runbook. For rate limit issues, see obsidian-rate-limits.
