Troubleshooting Guide

Common issues and solutions for Git codex projects and index files

Last updated: 2025-10-15

Troubleshooting Guide

Solutions to common issues with Git codex projects and index files.

Index File Issues

Files Not Showing Up

Problem: Files exist in repository but don't appear in file tree.

Possible Causes & Solutions:

  1. Excluded by patterns ```yaml patterns: exclude:

    • "docs/" # Excludes all files in docs/ ``` Solution**: Check your exclude patterns, remove blocking rules

  2. Hidden by gitignore

  3. Check .gitignore file

  4. ChapterWise respects gitignore patterns Solution: Remove file from .gitignore or commit it

  5. Unsupported file type

  6. Only .codex.yaml, .codex.json, .md, .txt, .json, .yaml supported Solution: Convert to supported format or add to patterns

  7. Marked as hidden ```yaml files:

    • path: "myfile.md" hidden: true # Won't show `` **Solution**: Removehidden: true` or enable "Show Hidden"

Wrong File Order

Problem: Files appear in unexpected order.

Solution:

# Add explicit order
files:
  - path: "first.md"
    order: 1
  - path: "second.md"
    order: 2
  - path: "third.md"
    order: 3

Or change display settings:

display:
  sortBy: "order"  # or "name", "modified", "type"

Folder Not Expanding

Problem: Folder stays collapsed when it should be open.

Solution:

structure:
  - path: "MyFolder/"
    expanded: true  # Set this

Index File Not Found

Problem: "No index file found" message.

Causes: 1. File named incorrectly 2. File in wrong location 3. File not committed to repository

Solution:

# Must be in repository root
# Must be named exactly:
index.codex.yaml
# OR
index.codex.json
# OR local version:
.index.codex.yaml

# Check location
ls -la index.codex.yaml

# Commit if needed
git add index.codex.yaml
git commit -m "Add index file"
git push

Validation Errors

"Invalid YAML format"

Problem: YAML syntax error.

Common Mistakes:

# ❌ Missing colon
structure
  - path: "folder/"

# ✅ Correct
structure:
  - path: "folder/"

# ❌ Wrong indentation
files:
- path: "file1.md"
  - path: "file2.md"  # Too much indent

# ✅ Correct
files:
  - path: "file1.md"
  - path: "file2.md"

Solution: Use a YAML validator or IDE with YAML support.

"Path field required"

Problem: Missing required path field.

# ❌ Missing path
files:
  - title: "My File"

# ✅ Correct
files:
  - path: "myfile.md"
    title: "My File"

"Path does not exist"

Problem: Referenced file not in repository.

Solution: 1. Check file exists: ls path/to/file 2. Check spelling and capitalization 3. Check file is committed: git status 4. Verify path is relative to repository root

"File too large"

Problem: Index file exceeds 1MB limit.

Solution: 1. Remove explicit file listings (use auto-detection) 2. Simplify structure 3. Remove verbose descriptions 4. Use patterns instead of file lists

Git Integration Issues

Repository Not Syncing

Problem: Changes pushed but not appearing in ChapterWise.

Checks: 1. Webhook configured correctly 2. Repository accessible 3. Branch matches tracked branch 4. No sync errors in project

Solution:

1. Check project sync status
2. Try manual sync: "Sync Now" button
3. Check webhook delivery in GitHub settings
4. Verify GitHub App still has access

Clone Failed

Problem: "Repository cloning failed" error.

Causes: - Repository too large (>1GB) - Private repo without access - Invalid URL - Network timeout

Solution: 1. Verify repository size 2. Check access permissions 3. Validate repository URL 4. Try again (may be temporary network issue)

Files Missing After Sync

Problem: Some files disappeared after sync.

Likely Cause: Files were deleted or moved in repository.

Solution: 1. Check git commit history 2. Verify files still exist in repository 3. Regenerate index to reflect current state

Performance Issues

Slow Index Generation

Problem: Index takes long time to generate.

Causes: - Too many files (>1000) - Deep folder nesting - Large files

Solutions: 1. Use exclude patterns: yaml patterns: exclude: - "archive/**" - "old-versions/**"

  1. Limit depth
  2. Remove large binary files from repository

File Tree Slow to Load

Problem: File tree loads slowly in browser.

Solutions: 1. Collapse folders by default: yaml structure: - path: "LargeFolder/" expanded: false

  1. Use display preferences: yaml display: groupBy: "folder" showHidden: false

  2. Break up large folders into smaller ones

Display Issues

Icons Not Showing

Problem: File/folder icons don't appear.

Solution: Icons are auto-assigned based on type. Ensure Phosphor icons are loading (check browser console).

Wrong Icon for File

Problem: File shows incorrect icon.

Solution: Override with custom icon:

files:
  - path: "special.md"
    icon: "ph-star"  # Custom icon

Formatting Looks Wrong

Problem: Text or layout appears incorrect.

Causes: - Browser cache - CSS not loading - Incompatible browser

Solution: 1. Hard refresh: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) 2. Clear browser cache 3. Try different browser 4. Update browser to latest version

Search & Filtering

Search Not Finding Files

Problem: Search doesn't return expected files.

Checks: 1. File is visible (not hidden) 2. File is in current view 3. Search is case-sensitive (depends on implementation)

Solution: 1. Enable "Show Hidden" if needed 2. Check file path and name 3. Try different search terms

Filter Not Working

Problem: Filter doesn't narrow results.

Solution: 1. Check filter syntax 2. Ensure files match criteria 3. Clear other filters 4. Refresh page

Common Error Messages

"Unauthorized"

Meaning: You don't have access to this project.

Solution: Ensure you're logged in and own the project.

"Not a Git project"

Meaning: Project is not linked to a Git repository.

Solution: This feature only works for Git-based projects.

"Index file corrupted"

Meaning: Index file is invalid or unreadable.

Solution: 1. Validate YAML syntax 2. Check file encoding (must be UTF-8) 3. Regenerate index from filesystem

"Failed to merge with filesystem"

Meaning: Index references files that don't exist.

Solution: 1. Update file paths in index 2. Regenerate index 3. Check for renamed/moved files

Best Practices to Avoid Issues

  1. Start Simple: Don't over-configure initially
  2. Test Incrementally: Add features one at a time
  3. Use Validation: Check YAML syntax before committing
  4. Keep Backups: Save working index before major changes
  5. Document Changes: Use git commit messages
  6. Regular Regeneration: Regenerate index after major repo changes

Getting Help

If you're still experiencing issues:

  1. Check Documentation:
  2. Index Format
  3. Best Practices

  4. Examples

  5. Validate Your Index:

  6. Use YAML validator
  7. Check against examples

  8. Test with minimal index first

  9. Check Logs:

  10. Browser console for client errors
  11. Server logs for backend issues

  12. GitHub webhook delivery logs

  13. Contact Support:

  14. Describe the issue clearly
  15. Include error messages
  16. Share relevant index file sections
  17. Mention browser and OS

Quick Diagnostics

Run through this checklist:

  • [ ] Index file is named correctly (index.codex.yaml)
  • [ ] Index file is in repository root
  • [ ] YAML syntax is valid
  • [ ] All referenced paths exist
  • [ ] File types are supported
  • [ ] No conflicting patterns
  • [ ] Folders have trailing slashes
  • [ ] No type fields (auto-detected)
  • [ ] Git repository is accessible
  • [ ] Webhook is configured (if using auto-sync)
  • [ ] Browser cache is clear

Still need help? Contact support with: - Error message - Your index file (relevant sections) - Steps to reproduce the issue - Browser and OS information