my-vault/06_Metadata/Reference/TROUBLESHOOTING.md

created, type, tags

created	type	tags
2026-01-06	reference	troubleshooting help faq

Troubleshooting Guide

Common issues and solutions for your Obsidian vault.

---

Quick Diagnostics

Before anything else, run:

git status          # Check Git state
git pull            # Sync latest changes
ls 00_Inbox/        # Check inbox

Most issues stem from: Git conflicts, file misplacement, or broken links.

---

Git Issues

"Permission denied (publickey)"

Problem: Can't push/pull from remote (SSH key issue)

Solution 1: Use HTTPS instead:

git remote set-url origin https://github.com/username/repo.git
git pull

Solution 2: Configure SSH key:

# Generate new SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"

# Add to GitHub: Settings → SSH Keys → Add Key
# Copy public key:
cat ~/.ssh/id_ed25519.pub

---

Git Conflicts After Pull

Problem:

CONFLICT (content): Merge conflict in filename.md
Automatic merge failed; fix conflicts and then commit the result.

Solution:

# 1. Check which files have conflicts
git status

# 2. Open conflicted files
# You'll see markers like:
#   <<<<<<< HEAD
#   Your local changes
#   =======
#   Remote changes
#   >>>>>>> origin/main

# 3. Edit files manually, choose which version to keep
# Delete conflict markers

# 4. Stage and commit
git add .
git commit -m "Resolve merge conflicts"
git push

Prevention:

• Always git pull before starting work
• Commit and push at end of each session
• Don't edit same file on multiple devices simultaneously

---

"Your branch is ahead by N commits"

Meaning: You have local commits not pushed to remote

Solution:

git push

---

"Your branch is behind by N commits"

Meaning: Remote has commits you don't have locally

Solution:

git pull

---

"Diverged branches"

Meaning: Both you and remote have different commits

Solution:

git pull                    # Will attempt auto-merge
# If conflicts occur, resolve manually (see above)
git add .
git commit -m "Resolve merge conflicts"
git push

---

Accidentally Committed Sensitive File

Immediate Action:

# Remove from Git tracking (keep local file)
git rm --cached sensitive-file.txt

# Add to .gitignore
echo "sensitive-file.txt" >> .gitignore

# Commit removal
git add .gitignore
git commit -m "Remove sensitive file from tracking"
git push

⚠️ Warning: File still exists in Git history. For complete removal, use BFG Repo-Cleaner (advanced).

---

Completely Reset to Remote

⚠️ DANGER: This discards ALL local changes

Use when: Local changes are broken beyond repair

# Backup first (if anything is valuable)
cp -r . ../vault-backup

# Reset to remote
git fetch origin
git reset --hard origin/main
git clean -fd

---

File Organization Issues

Inbox Overflow (> 50 items)

Problem: Inbox has too many unprocessed items

Solution:

# 1. Count items
ls 00_Inbox/ | wc -l

# 2. Schedule 30-60 minute processing session
# 3. Quick triage:
#    - Delete: Low-value items
#    - Archive: Outdated items
#    - Quick process: Easy decisions
#    - Batch process: Similar items together

# 4. Set calendar reminder for weekly review

Prevention:

• Process inbox weekly (non-negotiable)
• Capture fast, don't organize while capturing
• Use #needs-processing tag for complex items

---

Can't Find a File

Scenario: You know a file exists but can't locate it

Solution 1: Obsidian Search:

Ctrl+Shift+F (or Cmd+Shift+F)

Solution 2: Command line search:

# Search by filename
find . -name "*keyword*"

# Search by content
grep -r "keyword" . --include="*.md"

# Search with context
grep -r -C 3 "keyword" . --include="*.md"

Solution 3: Check common locations:

ls 00_Inbox/                # Recently added?
ls 04_Archive/              # Already archived?
git log --all --full-history -- "*keyword*"  # Deleted?

Solution 4: Git history:

# Find when file was moved/deleted
git log --all --full-history --summary | grep filename

# See file contents from past
git show <commit-hash>:path/to/file.md

---

Broken Links After Moving Files

Problem: Moved a file, now links are broken

Solution 1: Use update script:

pnpm attachments:update-links

Solution 2: Manual search and replace:

# Find all references to old path
grep -r "old-filename" . --include="*.md"

# Update manually in each file

Solution 3: Obsidian's built-in update:

• Obsidian automatically updates [[wiki-links]] when you move files in the app
• Use Obsidian file explorer to move files when possible

Prevention:

• Use Obsidian's file explorer to move files (auto-updates links)
• Or use pnpm attachments:update-links after moving
• Commit changes after any reorganization

---

File in Wrong Folder

Problem: File is in wrong PARA category

Solution:

# 1. Verify destination exists
ls 01_Projects/TargetProject/

# 2. Move file
mv "02_Areas/wrongplace/file.md" "01_Projects/TargetProject/file.md"

# 3. Update any links (if needed)
pnpm attachments:update-links

# 4. Commit
git add .
git commit -m "Organize: Moved file.md to correct location"
git push

---

Attachment Issues

Orphaned Attachments

Problem: Attachments in 05_Attachments/ not referenced anywhere

Solution:

# Find orphaned files
pnpm attachments:orphans

# Review each orphan:
# - Delete if truly unused
# - Or add reference to a note

---

Broken Image/Attachment Links

Problem: ![[image.png]] shows as broken link

Causes:

1. File doesn't exist
2. File path is wrong
3. File name has typo

Solution:

# 1. Check if file exists
ls 05_Attachments/ | grep image

# 2. Check organized folder
ls 05_Attachments/Organized/ | grep image

# 3. Search for file anywhere
find . -name "*image*"

# 4. Update link in note to correct path

Prevention:

• Use Obsidian's drag-and-drop to insert attachments (auto-correct paths)
• Keep attachments organized in 05_Attachments/
• Use descriptive file names

---

Attachment Folder Too Large

Problem: 05_Attachments/ is taking up too much space

Solution:

# 1. Check sizes
pnpm attachments:sizes

# 2. Identify large files
find 05_Attachments -type f -size +10M

# 3. Options:
#    - Compress images (use online tools)
#    - Delete unused files (check with orphans script)
#    - Move large videos outside vault (link externally)

Prevention:

• Compress images before adding
• Link to large videos externally (Google Drive, Dropbox)
• Regularly clean up unused attachments

---

Command/Script Issues

"pnpm: command not found"

Problem: Node.js/pnpm not installed or not in PATH

Solution:

# Install pnpm
npm install -g pnpm

# Or use npx instead
npx pnpm attachments:list

---

Script Fails with "Permission denied"

Problem: Script doesn't have execute permissions

Solution:

# Add execute permission
chmod +x .scripts/script-name.sh

# Or run with bash explicitly
bash .scripts/script-name.sh

---

Firecrawl Scripts Fail

Problem: pnpm firecrawl:scrape returns errors

Common Causes:

1. API key not set
2. Proxy not configured (if behind firewall)
3. Invalid URL

Solution:

# 1. Set up environment
source .scripts/setup-firecrawl-env.sh

# 2. Verify environment
echo $FIRECRAWL_API_KEY      # Should show your key
echo $HTTP_PROXY              # Should show proxy (if needed)

# 3. Test with simple URL
pnpm firecrawl:scrape "https://example.com" "test.md"

# 4. Check output
cat 00_Inbox/Clippings/test.md

---

Obsidian App Issues

Vault Not Syncing Properly

Problem: Changes in Obsidian don't appear in Git

Cause: Obsidian auto-save might be delayed

Solution:

1. Manually save note: Ctrl+S (or Cmd+S)
2. Wait 1-2 seconds for file to write
3. Then run git status to verify

---

"This vault is not an Obsidian vault"

Problem: Obsidian doesn't recognize vault folder

Solution:

# Check if .obsidian folder exists
ls -la .obsidian/

# If missing, re-open as vault in Obsidian:
# File → Open Folder as Vault → Select vault directory

---

Plugins Not Working

Problem: Installed plugins don't appear or function

Solution:

1. Check .obsidian/community-plugins.json exists
2. Settings → Community Plugins → Ensure not in restricted mode
3. Restart Obsidian
4. Re-enable plugins in Settings

---

Workflow Issues

Weekly Review Not Happening

Problem: Haven't done weekly review in weeks

Solution:

# 1. Schedule 30-45 minutes NOW
# 2. Open WEEKLY_REVIEW.md
# 3. At minimum, process inbox:
ls 00_Inbox/
# Move items to proper locations

# 4. Set recurring calendar reminder:
#    "Weekly Review - Every Sunday 10am"

---

Too Many Active Projects

Problem: 20+ projects, feeling overwhelmed

Solution:

# 1. List projects
ls 01_Projects/

# 2. For each project, ask:
#    - Worked on in last 30 days? → Keep active
#    - Haven't touched in 30+ days? → Archive
#    - No longer relevant? → Archive

# 3. Archive inactive projects
mv "01_Projects/OldProject" "04_Archive/Projects/OldProject"

# 4. Aim for 5-10 active projects maximum

---

Areas Becoming Dumping Grounds

Problem: An area has 50+ unrelated notes

Solution:

1. Review contents: What are these notes about?
2. Create sub-areas or projects: Group related notes
3. Move to resources: If just reference material
4. Archive: If outdated

Example:

Before:
02_Areas/Personal/
├── health-tip-1.md
├── health-tip-2.md
├── budget-2025.md
├── workout-plan.md
├── ... (50 more files)

After:
02_Areas/Health/           ← New area
├── workout-plan.md
└── health-tips/

02_Areas/Finances/         ← New area
└── budget-2025.md

03_Resources/Health/       ← Reference materials
└── health-tips/

---

Performance Issues

Obsidian Slow to Start

Causes:

1. Too many plugins
2. Vault too large
3. Indexing large files

Solution:

1. Disable unused plugins: Settings → Community Plugins
2. Archive old files: Move to 04_Archive/
3. Exclude large folders from search: Settings → Files & Links → Excluded files

---

Git Operations Slow

Causes:

1. Large binary files in repo
2. Too many commits in history

Solution:

# Check repo size
du -sh .git

# Find large files
find . -type f -size +10M

# Consider:
# - Git LFS for large files
# - .gitignore for unnecessary files
# - Clean up old binary files

---

Data Recovery

Accidentally Deleted File

Solution 1: Git history:

# Find when file was deleted
git log --all --full-history -- "path/to/file.md"

# Restore from specific commit
git checkout <commit-hash> -- "path/to/file.md"

Solution 2: Obsidian's file recovery:

• .obsidian/plugins/file-recovery/ (if plugin enabled)

Solution 3: System file recovery:

• Windows: Recycle Bin
• Mac: Trash
• Linux: ~/.local/share/Trash/

---

Vault Corrupted

⚠️ Extreme Case:

Solution:

# 1. Stop and assess damage
git status

# 2. If Git is intact, reset to last known good state
git log --oneline -20
git reset --hard <good-commit-hash>

# 3. If Git is broken, clone from remote
cd ..
git clone <remote-url> vault-restored
cd vault-restored

Prevention:

• Commit daily (creates restore points)
• Push to remote (offsite backup)
• Optional: External backup (Google Drive, Dropbox)

---

Getting Help

Self-Help Checklist

Before asking for help:

• Checked this troubleshooting guide
• Ran git status and git pull
• Searched Obsidian forums
• Googled the error message
• Checked GIT_WORKFLOW for Git issues
• Reviewed QUICK_REFERENCE for commands

---

Ask AI Assistant

Effective Questions:

✅ "How do I move files from Inbox to Projects?"
✅ "I'm getting this error: [paste error]. How do I fix it?"
✅ "What's the difference between Areas and Resources?"

❌ "It's broken" (too vague)
❌ "Nothing works" (no context)

---

External Resources

Obsidian Forums: https://forum.obsidian.md/ Git Documentation: https://git-scm.com/doc PARA Method: https://fortelabs.com/blog/para/

---

Preventive Maintenance

Daily

• git pull at start
• git push at end

Weekly

• Process inbox
• Review active projects
• Run pnpm attachments:orphans

Monthly

• Archive completed projects
• Clean up orphaned attachments
• Review and consolidate resources

Quarterly

• Deep archive review
• Check .gitignore is up to date
• Update documentation (CLAUDE.md, etc.)

---

Last Updated: 2026-01-06 See Also: CLAUDE, QUICK_REFERENCE, GIT_WORKFLOW