X402 Troubleshooting

By X402 Team | Last Updated: February 2026

Direct Answer

Common X402 issues include incorrect batch status tracking (fix by checking INDEX.md files), incomplete content items (verify against templates), Git merge conflicts (resolve manually then recommit), and template compliance failures (review template requirements and update content).

Detailed Explanation

Common Issues and Solutions

1. Batch Status Doesn't Match Reality

Symptoms

  • Batch shows "In Progress" but all items completed
  • Count shows (0/5) but items are checked off
  • Multiple batches marked "In Progress"

Root Causes

  • Forgot to update main INDEX.md
  • Didn't update completion count
  • Started new batch before completing current one

Solutions

Fix incorrect status: 

# Before (incorrect)

    

  • [ ] batch-001 — In Progress (0/5 titles)
    • 




After (correct)


    

  • [x] batch-001 — Complete (5/5 titles)

Verify all INDEX files:

  1. Check main INDEX.md batch status
  2. Open batch INDEX.md
  3. Count checked items
  4. Update counts to match
  5. Mark batch complete if all items checked

Prevention

  • Update status immediately after completing items
  • Use checklist in AGENT_INSTRUCTIONS.md
  • Review main INDEX.md before starting new batch

2. Content Doesn't Follow Template

Symptoms

  • Missing required sections
  • Quality standards not addressed
  • Inconsistent structure across batch
  • Placeholder text still present

Root Causes

  • Didn't reference template during creation
  • Template changed mid-batch
  • Creator unfamiliar with requirements
  • Rushed completion

Solutions

Compare to template: 

# View template and content side-by-side
diff templates/blueprint-template.md batch-001/content-item.md

Fix missing sections:

  1. Open template file
  2. Open content file
  3. Add missing sections
  4. Fill in required content
  5. Check off quality standards

Verify quality standards: 

## Quality Standards

    

  • [x] All required sections completed
    • 

  • [x] No placeholder text remains
    • 

  • [x] Formatting consistent
    • 

  • [x] Ready for production

Prevention

  • Always open template before creating content
  • Copy template structure as starting point
  • Review quality standards before marking complete
  • Don't modify templates mid-batch

3. Git Merge Conflicts

Symptoms 

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

Root Causes

  • Multiple people editing same file
  • Batch edits on different branches
  • Forgot to pull before starting work
  • Long-lived feature branch

Solutions

Resolve conflict manually: 

# 1. Open conflicted file

Look for conflict markers:



<<<<<<< HEAD

    

  • [ ] batch-001 — In Progress (3/5 titles)
    • 


=======

    

  • [ ] batch-001 — In Progress (4/5 titles)
    • 


>>>>>>> feature-branch



2. Choose correct version or combine:


    

  • [ ] batch-001 — In Progress (4/5 titles)
    • 




3. Remove conflict markers


4. Stage and commit

git add INDEX.md
git commit -m "Resolve merge conflict in INDEX.md"

Prevention

  • Pull latest changes before starting work
  • Communicate about batch ownership
  • Complete batches quickly to reduce conflict window
  • Use branch-per-batch approach

4. Lost or Missing Files

Symptoms

  • Content file not in batch folder
  • Can't find completed work
  • File was definitely created but now missing

Root Causes

  • Saved in wrong directory
  • Didn't commit changes
  • Git ignored the file
  • Deleted accidentally

Solutions

Search for file: 

# Search entire repository
find . -name "missing-file.md"



Search Git history

git log --all --full-history -- "/missing-file.md"

Check .gitignore: 

# See if file is ignored
git check-ignore -v batch-001/file.md



If ignored, update .gitignore

Recover from Git history: 

# Find when file was deleted
git log --diff-filter=D -- batch-001/file.md



Restore from specific commit

git checkout <commit-hash> -- batch-001/file.md

Prevention

  • Commit frequently after completing each item
  • Verify files with git status before committing
  • Double-check .gitignore patterns
  • Use descriptive commit messages

5. Template Updates Breaking Consistency

Symptoms

  • Batch has mixed template versions
  • Some items have new sections, others don't
  • Quality standards vary between items
  • Confusion about correct format

Root Causes

  • Changed template mid-batch
  • Different creators used different template versions
  • Template evolved without documentation

Solutions

Document template version: 

# In batch INDEX.md

Notes

Using blueprint-template.md v2.0 for all items
Template frozen for this batch

Retroactive updates: If template must change mid-batch:

  1. Update template file
  2. List all affected items
  3. Update each item to new template
  4. Commit as "Update batch-001 to template v2.1"
  5. Document in batch notes

Prevention

  • Lock templates at batch start
  • Note template changes for next batch
  • Version templates if frequently updated
  • Communicate template changes to team

6. Incorrect File Naming

Symptoms

  • File names don't match content
  • Inconsistent naming across batch
  • Files hard to find
  • Links between files broken

Root Causes

  • No naming convention established
  • Typos in filenames
  • Spaces in filenames causing issues
  • Case sensitivity problems

Solutions

Establish naming convention: 

# Good naming
what-is-x402.md
how-x402-works.md
x402-implementation-guide.md



Bad naming

What Is X402.md
How X402 Works!.md
x402 implementation guide.md

Rename files: 

# Rename using Git (preserves history)
git mv "Old File Name.md" "new-file-name.md"
git commit -m "Rename file to follow naming convention"

Prevention

  • Document naming convention in README
  • Use lowercase-with-dashes format
  • No spaces in filenames
  • Be consistent across all batches

7. Broken Links Between Content

Symptoms

  • Clicking link returns 404 or error
  • "Related Questions" links don't work
  • Cross-references broken

Root Causes

  • Referenced file renamed
  • Relative path incorrect
  • File moved to different batch
  • Typo in link

Solutions

Find broken links: 

# Search for markdown links
grep -r "\.\" batch-/



Check if linked files exist


Link text

Fix relative paths: 

# If linking from batch-001/file-a.md to batch-001/file-b.md
Link text



If linking to different batch

Link text

Prevention

  • Use relative paths consistently
  • Update links when renaming files
  • Test links before marking content complete
  • Consider using file references instead of paths

8. Quality Standards Not Met

Symptoms

  • Content marked complete but has issues
  • Reviewers finding problems
  • Rework required
  • Quality inconsistent

Root Causes

  • Rushed through quality checks
  • Unclear what standards mean
  • No review process
  • Time pressure

Solutions

Implement review checklist: 

## Before Marking Complete

    

  1. Read through entire content
    2. 

  2. Verify all sections complete
    3. 

  3. Check spelling and grammar
    4. 

  4. Test any code examples
    5. 

  5. Verify links work
    6. 

  6. Confirm formatting consistent
    7. 

  7. Have peer review (if team)
    8. 

  8. Check all quality standards boxes

Add specific quality criteria: 

## Quality Standards

    

  • [ ] Zero spelling errors (run spell check)
    • 

  • [ ] All code examples tested and working
    • 

  • [ ] No placeholder text like [TODO] or [TBD]
    • 

  • [ ] Formatting matches style guide
    • 

  • [ ] Links verified working
    • 

  • [ ] Technical accuracy confirmed by SME
    • 

  • [ ] Peer reviewed and approved
    • 

  • [ ] Ready for production

Prevention

  • Don't check off items until truly complete
  • Schedule review time into estimates
  • Use automated checks where possible
  • Treat quality standards as hard requirements

Debugging Workflow

When Something Goes Wrong

Step 1: Identify the Issue

  • What's not working as expected?
  • What should be happening?
  • When did it start?

Step 2: Check Recent Changes 

# See recent commits
git log --oneline -10



See what changed

git diff HEAD~1


See file history

git log -p batch-001/INDEX.md

Step 3: Review Documentation

  • Check AGENT_INSTRUCTIONS.md
  • Review template requirements
  • Consult best practices

Step 4: Verify File Structure 

# List all files
ls -R



Check for expected structure

tree batch-001/

Step 5: Check Git Status 

git status
git diff
git log --oneline

Step 6: Fix and Verify

  • Make necessary changes
  • Test the fix
  • Commit with clear message
  • Verify issue resolved

Prevention Strategies

1. Consistent Workflow

Follow the same process every time:
  1. Check status in main INDEX.md
  2. Open batch INDEX.md
  3. Pick unchecked item
  4. Open template
  5. Create content
  6. Verify quality standards
  7. Check off item
  8. Commit
  9. Repeat

2. Frequent Commits

Commit after each completed item: 
git add batch-001/new-content.md batch-001/INDEX.md
git commit -m "Complete: [Content Title]"

3. Regular Reviews

  • Review INDEX files before starting new work
  • Check completed content periodically
  • Verify batch status matches reality
  • Clean up any inconsistencies

4. Clear Communication

For teams:
  • Announce when starting a batch
  • Share completion status
  • Coordinate on template changes
  • Review each other's work

5. Documentation

Maintain README with:
  • Naming conventions
  • Template locations
  • Quality standards
  • Common issues and fixes
  • Contact for questions

Getting Help

Self-Service

  1. Read AGENT_INSTRUCTIONS.md
  2. Check template examples
  3. Review best practices document
  4. Search Git history for similar issues

Team Support

  1. Ask team members who've completed batches
  2. Review pull requests for examples
  3. Pair with experienced creator
  4. Request formal review

External Resources

  1. Markdown syntax guides
  2. Git documentation
  3. Text editor help docs
  4. Version control tutorials

Related Questions

  • What is X402?
  • How does X402 work?
  • X402 best practices
  • How to implement X402?

Quality Standards

  • [x] Meets brand voice requirements
  • [x] Follows formatting standards
  • [x] Includes all required elements
  • [x] Ready for production

Start Building with X402

Get our free X402 Implementation Starter Kit with ready-to-use templates, code examples, and best practices.

What is included:

  • Quick-start implementation templates
  • API integration examples
  • Configuration best practices guide

Get the Free Starter Kit