wiki_ghostguild/docs/TROUBLESHOOTING.md

# Troubleshooting Guide

**For:** Wiki-GhostGuild Content Contributors

Common issues and solutions.

---

## Obsidian Issues

### Obsidian Won't Open Vault

**Symptom:** "Vault not found" or error when opening folder

**Solutions:**

1. **Check path:** Make sure you're opening the exact right folder
   ```bash
   # Should be this:
   /path/to/wiki-ghostguild/content/articles/

   # Not this:
   /path/to/wiki-ghostguild/  # Parent folder
   /path/to/wiki-ghostguild/content/  # Wrong subfolder
   ```

2. **Full path issues:** On Mac, use full path starting with `/Users/`
   ```
   /Users/yourname/Sites/wiki-ghostguild/content/articles/
   ```

3. **Permissions:** Make sure you have read/write access
   ```bash
   ls -ld /path/to/wiki-ghostguild/content/articles/
   # Should show: drwxrwxr-x (or similar with r+w)
   ```

4. **Restart Obsidian:** Close completely and reopen

---

### Wikilinks Showing as Red (Broken)

**Symptom:** `[[Page Name]]` appears in red in Obsidian

**Causes & Solutions:**

1. **Typo in page name**
   ```
   ❌ [[Communication Norms]] - Missing full title
   ✅ [[Communication Norms Document for Game Studios]]
   ```
   → Links must match article titles exactly

2. **Title in frontmatter doesn't match**
   ```yaml
   # In article file:
   ---
   title: "Communication Norms Document for Game Studios"
   ---

   # Then this works:
   [[Communication Norms Document for Game Studios]]

   # But this doesn't:
   [[Communication Norms]] # Partial match doesn't work
   ```

3. **Cache issue**
   - Close Obsidian completely
   - Wait 10 seconds
   - Reopen
   - Wikilink should show as blue now

4. **Check article exists**
   - Open Graph view: Left sidebar → "Graph" tab
   - Search for the article title
   - If not there, article file is missing or title is wrong

---

### Images Not Saving

**Symptom:** Paste image, nothing appears or goes to wrong location

**Solutions:**

1. **Check attachment folder setting**
   - Settings → Files & Links
   - "Attachment folder path" should be: `../../public/img`
   - If different, change it back

2. **Folder doesn't exist**
   ```bash
   # Check:
   ls /path/to/wiki-ghostguild/public/img/

   # If not there, create:
   mkdir -p /path/to/wiki-ghostguild/public/img/
   ```

3. **Try again**
   - Paste image: `Cmd+V` (Mac) or `Ctrl+V`
   - Should prompt for filename
   - Edit if needed and confirm
   - Image should appear and be saved to `/public/img/`

4. **Check permissions**
   ```bash
   ls -ld /path/to/wiki-ghostguild/public/img/
   # Should be writable (w flag)
   ```

5. **Restart Obsidian**
   - Close completely
   - Reopen vault
   - Try pasting again

---

### Obsidian Git Not Working

**Symptom:** Obsidian Git plugin not appearing or not committing

**Solutions:**

1. **Plugin not enabled**
   - Settings → Community plugins
   - Search "Obsidian Git"
   - Toggle ON if disabled

2. **Restricted mode**
   - Settings → Community plugins
   - If "Restricted mode ON" shows, click toggle
   - Enable plugins
   - Refresh

3. **Git not installed**
   ```bash
   # Check if git is available:
   which git
   # Should show: /usr/bin/git or similar

   # If not, install:
   # Mac: brew install git
   # Windows: Download from git-scm.com
   ```

4. **Not in git repository**
   ```bash
   # Check:
   cd /path/to/wiki-ghostguild
   git status

   # Should show branch info, not "fatal: not a git repository"
   ```

5. **Configure git identity**
   ```bash
   git config user.name "Your Name"
   git config user.email "your@email.com"
   ```

6. **Reload plugin**
   - Settings → Community plugins → Obsidian Git → Reload

---

## Git Issues

### Can't Push (Remote Rejection)

**Symptom:** "Permission denied" or "rejected" when pushing

**Causes:**
1. Not authenticated to Forgejo
2. Remote URL is wrong
3. Branch is wrong

**Solutions:**

1. **Check remote URL**
   ```bash
   cd wiki-ghostguild
   git remote -v
   # Should show:
   # origin https://your-forgejo.com/org/wiki-ghostguild.git
   ```

2. **Fix if wrong**
   ```bash
   git remote set-url origin https://your-forgejo.com/org/wiki-ghostguild.git
   git push
   ```

3. **Authenticate to Forgejo**
   - Generate personal token (Forgejo settings)
   - Use token as password when git prompts
   - Or set up SSH key

4. **Check branch**
   ```bash
   git branch
   # Should be on 'main' (or whatever default branch)
   ```

---

### Merge Conflict

**Symptom:** "CONFLICT" in Obsidian Git or error when pulling

**Solutions:**

1. **See conflict file**
   - Look for `conflict-files-obsidian-git.md`
   - Or use `git status` to see conflicted files

2. **Resolve conflict**
   ```markdown
   # Find conflict markers:
   <<<<<<< HEAD
   Your version (what you wrote)
   =======
   Their version (what they wrote)
   >>>>>>> main

   # Delete one section and keep what's correct
   # Or merge both if both are needed
   # Remove the markers: <<<<, ====, >>>>
   ```

3. **After resolving**
   ```bash
   # Mark as resolved
   git add file-name.md

   # Commit the resolution
   git commit -m "Resolve conflict in file-name.md"

   # Push
   git push
   ```

4. **Prevent future conflicts**
   - **Pull before editing:** Start work each day with `git pull`
   - **Work on different files:** If both editing, use different articles
   - **Push frequently:** Don't let changes pile up

---

## Building Issues

### Build Fails: "error TS..."

**Symptom:** `npm run generate` shows TypeScript errors

**Solutions:**

1. **Check file syntax**
   ```bash
   # Errors show file path and line number
   # Fix the TypeScript error mentioned
   ```

2. **Clear cache and try again**
   ```bash
   rm -rf .nuxt .output
   npm run generate
   ```

3. **Check dependencies**
   ```bash
   npm install
   npm run generate
   ```

---

### Build Fails: "Invalid frontmatter"

**Symptom:** Build error about article YAML

**Solutions:**

1. **Check YAML syntax**
   ```yaml
   # ✅ Correct syntax
   ---
   title: "My Article"
   tags:
     - tag1
     - tag2
   ---

   # ❌ Common errors
   tags: tag1, tag2  # Wrong - should be array with brackets
   title: My Article  # Missing quotes (usually ok, but can cause issues)
   author "Name"  # Missing colon
   ```

2. **Validate YAML online**
   - Copy frontmatter to https://www.yamllint.com
   - Fix any errors it shows

3. **Check required fields**
   ```yaml
   # Minimum required:
   ---
   title: "Article Title"
   ---

   # All other fields are optional
   ```

---

### Build Fails: "No such file"

**Symptom:** "Cannot find module" or "ENOENT" error

**Solutions:**

1. **Check file exists**
   ```bash
   ls app/server/plugins/wikilink-transform.ts
   ls content.config.ts
   ```

2. **Check for typos in imports**
   - Look at error message for exact path
   - Make sure it matches actual file

3. **Reinstall dependencies**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   npm run generate
   ```

---

### Dev Server Slow / Hot Reload Not Working

**Symptom:** Changes take a long time to appear, or don't appear

**Solutions:**

1. **Restart dev server**
   ```bash
   # Stop: Ctrl+C
   npm run dev
   ```

2. **Clear cache**
   ```bash
   rm -rf .nuxt
   npm run dev
   ```

3. **Port conflict**
   ```bash
   # If port 3000 taken:
   npm run dev -- -p 3001
   # Then visit: http://localhost:3001
   ```

4. **File too large**
   - If a single article is very large (>10,000 lines)
   - It may reload slowly
   - Consider splitting into multiple articles

---

## Deployment Issues

### Website Shows Old Content

**Symptom:** Changes pushed but don't appear on live site

**Causes:**
1. Build not triggered
2. Cache not cleared
3. Deployment not complete

**Solutions:**

1. **Force rebuild on server**
   ```bash
   cd wiki-ghostguild
   git pull
   npm run generate
   # Restart web server
   ```

2. **Clear server cache**
   - Check hosting provider docs
   - Usually: Clear CDN cache or restart server

3. **Check deployment status**
   - Look at CI/CD pipeline status
   - Check if build completed successfully

---

## Networking Issues

### Can't Clone Repository

**Symptom:** "Permission denied" or authentication fails

**Solutions:**

1. **Set up SSH key (recommended)**
   ```bash
   ssh-keygen -t ed25519 -C "your@email.com"
   # Add public key to Forgejo settings
   git clone git@your-forgejo.com:org/wiki-ghostguild.git
   ```

2. **Or use HTTPS with token**
   ```bash
   # Generate personal token in Forgejo
   git clone https://your-forgejo.com/org/wiki-ghostguild.git
   # Use token as password when prompted
   ```

3. **Internet connection**
   - Check you have internet
   - Try `ping google.com`

---

### Port Already in Use

**Symptom:** `npm run dev` fails with "port already in use"

**Solutions:**

```bash
# Find what's using the port
ps aux | grep nuxt
ps aux | grep node

# Kill the process (replace 12345 with PID)
kill -9 12345

# Or use different port
npm run dev -- -p 3001
```

---

## Article Issues

### Frontmatter Missing After Editing

**Symptom:** Content looks corrupted in Obsidian

**Solutions:**

1. **Check file**
   ```bash
   head -20 content/articles/article-name.md
   # Should start with:
   # ---
   # title: ...
   ```

2. **Recover from git**
   ```bash
   git checkout content/articles/article-name.md
   # Reverts to last committed version
   ```

3. **Check git status**
   ```bash
   git status
   # Should show what's changed
   ```

---

### Article Not Appearing in List

**Symptom:** Article is in /content/articles/ but doesn't show up

**Solutions:**

1. **Check frontmatter**
   ```yaml
   ---
   title: "Article Title"
   published: true  # Must be true or missing (default true)
   ---
   ```

2. **Check accessibility**
   ```yaml
   # If accessLevel is wrong, won't show:
   accessLevel: "member"  # User must be logged in

   # Try public for testing:
   accessLevel: "public"
   ```

3. **Check file saved**
   ```bash
   git status
   # If file shows modified, haven't committed yet
   ```

4. **Rebuild**
   ```bash
   npm run generate
   npm run preview
   # Check at http://localhost:3000
   ```

---

## Getting More Help

If not in this guide:

1. **Check the docs:**
   - `OBSIDIAN_SETUP_GUIDE.md` - User guide
   - `TECHNICAL_ARCHITECTURE.md` - How it works

2. **Check error message:**
   - Copy exact error
   - Search online
   - Try suggestion from error

3. **Check logs:**
   ```bash
   npm run dev 2>&1 | tee build.log
   # Look for warnings/errors
   # Look for file paths that don't exist
   ```

4. **Ask team:**
   - Slack/Discord
   - Comment in pull request
   - Email team lead

---

**Remember:** Most issues are related to:
- ❌ Wrong folder path
- ❌ Missing git configuration
- ❌ Typo in article title
- ❌ Stale cache

99% of the time, one of these fixes it:
1. `rm -rf .nuxt && npm run dev`
2. `git pull`
3. `npm install`
4. Restart Obsidian
5. Restart terminal

---

**Last Updated:** November 2025