obsidian-claude-pkm/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and their solutions. If you can't find your issue here, check the community forums or documentation.

Quick Fixes

Before Anything Else, Try These:

1. Restart Obsidian

   • Completely close and reopen
   • Many issues resolve with a fresh start

2. Check File Permissions

   ls -la ~/Documents/ObsidianPKM
   # Should show your user as owner
   

3. Verify Claude Code

   claude --version
   # Should show version number
   

4. Pull Latest Changes

   git pull origin main
   # Get any updates
   

Common Issues

Obsidian Issues

"Cannot open vault" Error

Problem: Obsidian won't open your vault folder

Solutions:

1. Check folder exists:

   cd ~/Documents/ObsidianPKM
   ls -la
   

2. Reset Obsidian settings:

   # Backup first
   mv .obsidian .obsidian.backup
   # Restart Obsidian
   

3. Check for corrupted files:

   # Find files with issues
   find . -name "*.md" -exec file {} \; | grep -v "ASCII text"
   

Templates Not Working

Problem: Daily template doesn't create properly

Solutions:

1. Verify template location:

   Templates/Daily Template.md should exist
   

2. Check template settings:

   • Settings → Templates
   • Template folder location: "Templates"

3. Check date format:

   {{date}} and {{time}} should work
   

Links Not Working

Problem: Wiki links don't connect

Solutions:

1. Check link format in settings:

   • Settings → Files & Links
   • Use Wiki Links: ON
   • New link format: Relative path

2. Verify file exists:

   • Broken links appear faded
   • Click to create missing file

Claude Code Issues

"Command not found: claude"

Problem: Claude Code CLI not installed or not in PATH

Solutions:

1. Install Claude Code:

   # Check installation guide
   # https://code.claude.com/docs
   

2. Add to PATH:

   # Add to ~/.bashrc or ~/.zshrc
   export PATH="$PATH:/path/to/claude"
   source ~/.bashrc
   

Commands Not Recognized

Problem: /daily, /weekly etc. not working

Solutions:

1. Check command files exist:

   ls -la .claude/commands/
   # Should show daily.md, weekly.md, etc.
   

2. Copy commands if missing:

   cp claude-commands/* .claude/commands/
   

3. Check file permissions:

   chmod 644 .claude/commands/*.md
   

"Context too long" Error

Problem: Too many files loaded with /onboard

Solutions:

1. Load specific context:

   claude code /onboard Projects/CurrentProject
   

2. Clean up CLAUDE.md files:

   • Remove outdated information
   • Keep only essential context

3. Use selective loading:

   # Skip old projects
   claude code /onboard --exclude Archives
   

Git Issues

"Failed to push" Error

Problem: Can't push to GitHub

Solutions:

1. Pull first:

   git pull --rebase origin main
   git push
   

2. Check remote:

   git remote -v
   # Should show origin URLs
   

3. Fix authentication:

   # Use personal access token
   git remote set-url origin https://TOKEN@github.com/user/repo.git
   

Merge Conflicts

Problem: Conflicts when pulling/pushing

Solutions:

1. View conflicts:

   git status
   # Shows conflicted files
   

2. Resolve manually:

   • Open conflicted files
   • Look for <<<<<<< markers
   • Choose correct version
   • Remove markers

3. Complete merge:

   git add .
   git commit -m "Resolved conflicts"
   git push
   

Large File Issues

Problem: Git rejects large files

Solutions:

1. Use Git LFS:

   git lfs track "*.pdf"
   git lfs track "*.png"
   git add .gitattributes
   

2. Add to .gitignore:

   *.pdf
   *.mov
   *.zip
   

3. Remove from history:

   git filter-branch --tree-filter 'rm -f path/to/large/file' HEAD
   

Daily Note Issues

Wrong Date Format

Problem: Daily note has incorrect date

Solutions:

1. Check template variables:

   {{date:YYYY-MM-DD}}  # Standard format
   {{date:dddd, MMMM DD, YYYY}}  # Long format
   

2. Verify system date:

   date
   # Should show correct date/time
   

3. Set timezone:

   export TZ='America/New_York'
   

Duplicate Daily Notes

Problem: Multiple notes for same day

Solutions:

1. Check naming convention:

   • Should be YYYY-MM-DD.md
   • No spaces or special characters

2. Merge duplicates:

   # Copy content from duplicate
   # Paste into main note
   # Delete duplicate
   

3. Prevent future duplicates:

   • Always use /daily command
   • Don't create manually

GitHub Action Issues

Workflow Not Triggering

Problem: GitHub Action doesn't run

Solutions:

1. Check workflow file:

   # .github/workflows/claude.yml should exist
   

2. Verify triggers:

   on:
     issues:
       types: [opened, edited]
   

3. Check Actions enabled:

   • Repository → Settings → Actions
   • Actions permissions: Allow

OAuth Token Invalid

Problem: CLAUDE_CODE_OAUTH_TOKEN not working

Solutions:

1. Regenerate token:

   • Visit Claude Code documentation
   • Follow OAuth setup guide

2. Update secret:

   • Repository → Settings → Secrets
   • Update CLAUDE_CODE_OAUTH_TOKEN

3. Check token permissions:

   • Needs repo access
   • Needs workflow access

Performance Issues

Obsidian Running Slowly

Problem: Vault takes long to load or respond

Solutions:

1. Reduce vault size:

   # Archive old notes
   mv "Daily Notes/2023*" Archives/2023/
   

2. Disable unused plugins:

   • Settings → Community plugins
   • Disable what you don't use

3. Clear cache:

   rm -rf .obsidian/cache
   

4. Optimize images:

   # Compress images
   find . -name "*.png" -exec pngquant --ext .png --force {} \;
   

Search Not Working

Problem: Can't find notes with search

Solutions:

1. Rebuild search index:

   • Settings → About → Reindex vault

2. Check search syntax:

   "exact phrase"
   tag:#daily
   file:2024-01-15
   

3. Remove special characters from filenames

Platform-Specific Issues

macOS

"Operation not permitted"

# Grant Obsidian full disk access
System Preferences → Security & Privacy → Full Disk Access

iCloud Sync Issues

• Don't put vault in iCloud Drive
• Use Git for synchronization instead
• Or use Obsidian Sync service

Windows

Path Too Long

# Enable long paths
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Line Ending Issues

# Configure Git
git config --global core.autocrlf true

Linux

Permission Denied

# Fix permissions
chmod -R 755 ~/Documents/ObsidianPKM
chown -R $USER:$USER ~/Documents/ObsidianPKM

Missing Dependencies

# Install required packages
sudo apt-get update
sudo apt-get install git curl

Recovery Procedures

Restore from Backup

Using Git

# View history
git log --oneline

# Restore to previous commit
git reset --hard COMMIT_HASH

# Or restore single file
git checkout COMMIT_HASH -- path/to/file.md

Using File System

# If you have Time Machine (macOS)
# Or File History (Windows)
# Or Backups (Linux)

Rebuild Vault

If vault is corrupted:

# 1. Backup current vault
cp -r ~/Documents/ObsidianPKM ~/Documents/ObsidianPKM.backup

# 2. Create fresh vault
cp -r vault-template ~/NewVault

# 3. Copy your notes
cp -r ~/Documents/ObsidianPKM.backup/Daily\ Notes/* ~/NewVault/Daily\ Notes/
cp -r ~/Documents/ObsidianPKM.backup/Projects/* ~/NewVault/Projects/

# 4. Reinitialize Git
cd ~/NewVault
git init
git add .
git commit -m "Rebuilt vault"

Emergency Access

When locked out:

1. Access via GitHub.com
2. Edit files in browser
3. Download as ZIP if needed
4. Use mobile app as backup

Preventive Measures

Regular Maintenance

Weekly

# Clean up
claude code "Archive completed tasks and old notes"

# Backup
git push origin main

Monthly

# Optimize
claude code "Identify and remove duplicate content"

# Update
git pull origin main

Quarterly

# Review system
claude code "Analyze vault structure and suggest improvements"

# Clean dependencies
rm -rf node_modules .obsidian/cache

Backup Strategy

1. Version Control: Git commits daily
2. Cloud Backup: GitHub private repo
3. Local Backup: Time Machine/File History
4. Export Backup: Monthly markdown export

Getting Help

Resources

• Obsidian Forum
• Claude Code Docs
• GitHub Issues

Debug Information

When asking for help, provide:

# System info
uname -a

# Obsidian version
# (Check in Settings → About)

# Claude version
claude --version

# Git status
git status
git remote -v

# Vault structure
ls -la ~/Documents/ObsidianPKM

Community Support

• Discord channels
• Reddit: r/ObsidianMD
• Twitter: #ObsidianMD

---

Remember: Most issues have simple solutions. Stay calm, check the basics, and work through systematically.