---
created: 2026-01-06
type: reference
tags: [troubleshooting, help, faq]
---

# Troubleshooting Guide

Common issues and solutions for your Obsidian vault.

---

## Quick Diagnostics

**Before anything else, run**:

```bash
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**:
```bash
git remote set-url origin https://github.com/username/repo.git
git pull
```

**Solution 2: Configure SSH key**:
```bash
# 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**:
```bash
# 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**:
```bash
git push
```

---

### "Your branch is behind by N commits"

**Meaning**: Remote has commits you don't have locally

**Solution**:
```bash
git pull
```

---

### "Diverged branches"

**Meaning**: Both you and remote have different commits

**Solution**:
```bash
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**:
```bash
# 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
ls 00_Inbox/                # Recently added?
ls 04_Archive/              # Already archived?
git log --all --full-history -- "*keyword*"  # Deleted?
```

**Solution 4: Git history**:
```bash
# 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**:
```bash
pnpm attachments:update-links
```

**Solution 2: Manual search and replace**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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]]