jennie/wiki_ghostguild
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki_ghostguild/docs/TROUBLESHOOTING.md

11 KiB
Raw Blame History

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

    # 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

    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

    # 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

    # 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

    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

    # 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

    # Check:
cd /path/to/wiki-ghostguild
git status

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

  5. Configure git identity

    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

    cd wiki-ghostguild
git remote -v
# Should show:
# origin https://your-forgejo.com/org/wiki-ghostguild.git

  2. Fix if wrong

    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

    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

    # 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

    # 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

    # Errors show file path and line number
# Fix the TypeScript error mentioned

  2. Clear cache and try again

    rm -rf .nuxt .output
npm run generate

  3. Check dependencies

    npm install
npm run generate

Build Fails: "Invalid frontmatter"

Symptom: Build error about article YAML

Solutions:

  1. Check YAML syntax

    # ✅ 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

  3. Check required fields

    # 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

    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

    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

    # Stop: Ctrl+C
npm run dev

  2. Clear cache

    rm -rf .nuxt
npm run dev

  3. Port conflict

    # 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

    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)

    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

    # 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:

# 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

    head -20 content/articles/article-name.md
# Should start with:
# ---
# title: ...

  2. Recover from git

    git checkout content/articles/article-name.md
# Reverts to last committed version

  3. Check git status

    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

    ---
title: "Article Title"
published: true  # Must be true or missing (default true)
---

  2. Check accessibility

    # If accessLevel is wrong, won't show:
accessLevel: "member"  # User must be logged in

# Try public for testing:
accessLevel: "public"

  3. Check file saved

    git status
# If file shows modified, haven't committed yet

  4. Rebuild

    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:

    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