Obsidian Debug Bundle

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:

# macOS
VAULT_PATH=~/Documents/MyVault

# Linux
VAULT_PATH=~/Obsidian/MyVault

# Windows (Git Bash)
VAULT_PATH="/c/Users/$USER/Documents/MyVault"

# Verify it's a valid vault
ls "$VAULT_PATH/.obsidian/app.json" && echo "Valid vault" || echo "Not a vault"

Step 2: Collect Obsidian Version and App Settings

# Obsidian version is in the installer log or app settings
cat "$VAULT_PATH/.obsidian/app.json" 2>/dev/null | python3 -m json.tool

# Check installer version (macOS)
mdls -name kMDItemVersion /Applications/Obsidian.app 2>/dev/null

# Check installer version (Linux, snap)
snap info obsidian 2>/dev/null | grep installed

Step 3: List Installed Plugins and Their Versions

# Active community plugins
echo "=== Active Plugins ==="
cat "$VAULT_PATH/.obsidian/community-plugins.json" 2>/dev/null | python3 -m json.tool

# Plugin details (name, version, minAppVersion)
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

# Check for custom CSS snippets
echo "=== CSS Snippets ==="
ls "$VAULT_PATH/.obsidian/snippets/" 2>/dev/null || echo "No snippets directory"

# Check active theme
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 ==="
# File counts by type
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)"

# Vault size
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:

// Paste in Obsidian's Developer Console
(() => {
  const errors = [];
  const originalError = console.error;
  console.error = (...args) => {
    errors.push({ time: new Date().toISOString(), message: args.map(String).join(' ') });
    originalError.apply(console, args);
  };

  // After reproducing the issue, run:
  // copy(JSON.stringify(errors, null, 2))
  // This copies the error log to clipboard

  console.log(`Error capture active. Reproduce your issue, then run:
    copy(JSON.stringify(errors, null, 2))`);
})();

Alternatively, check for existing errors:

// Quick dump of plugin load errors
app.plugins.manifests; // All registered plugins
app.plugins.enabledPlugins; // Currently enabled set
// Check if a specific plugin failed to load:
app.plugins.plugins['your-plugin']; // undefined = failed to load

Step 7: Detect CSS Conflicts

# Check for snippet overrides that might conflict
for snippet in "$VAULT_PATH/.obsidian/snippets"/*.css; do
  [ -f "$snippet" ] || continue
  echo "=== $(basename "$snippet") ==="
  # Look for broad selectors that commonly cause conflicts
  grep -n 'body\b\|\.app-container\|\.workspace\|\.markdown-preview\|!important' "$snippet" | head -20
done

# Check theme CSS size (large themes are conflict-prone)
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'
# Obsidian Debug Report
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

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

• Obsidian Bug Reports Forum
• Plugin Developer Help
• Obsidian Discord #plugin-dev
• Obsidian Developer Console

Next Steps

For systematic incident response, see obsidian-incident-runbook. For rate limit issues, see obsidian-rate-limits.