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

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

• 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.