Waymaker
Sync

Troubleshooting Waymaker Sync

This guide helps you diagnose and fix common Waymaker Sync issues. Start with Quick Checks, then move to specific issues if needed.

FixesHelp
Last updated: February 1, 2026•8 minutes read

Troubleshooting Waymaker Sync

Difficulty: Intermediate

Overview

This guide helps you diagnose and fix common Waymaker Sync issues. Start with Quick Checks, then move to specific issues if needed.

Quick Checks

Before diving into specific issues, verify these basics:

1. Check Sync Status

waymaker_sync_status

Expected output:

  • running: true
  • filesWatched: [number > 0]
  • errorCount: 0

2. Verify Configuration

Check .commander/config.json exists and contains valid IDs.

3. Confirm Environment Variables

echo $WAYMAKER_API_KEY
echo $WAYMAKER_APPS_URL

Both should print values (not empty).

Common Issues

Files Not Syncing

Symptoms: Create/edit markdown file, nothing appears in Commander.

Checklist:

  1. Frontmatter present?

    ---
sync:
  type: task
---

    Files without sync: are ignored.

  2. File in watched folder? Check watch_patterns in config. Default: docs/**/*.md

  3. File extension correct? Only .md files are synced.

  4. Ignored by pattern? Check ignore_patterns doesn't exclude your file.

Fix: Add proper frontmatter and ensure file is in a watched folder.

Files Watched = 0

Symptoms: waymaker_sync_status shows filesWatched: 0

Causes:

  • Sync daemon not fully initialized
  • Watch patterns don't match any files
  • Project path incorrect

Fixes:

  1. Wait a moment - Initial scan takes a few seconds
  2. Check watch patterns: 
    "watch_patterns": ["docs/**/*.md"]
  3. Verify files exist: 
    ls docs/**/*.md

Documents Not Visible in Explorer

Symptoms: Sync reports success, but documents don't appear in Commander's Explorer.

Causes:

  • Organization ID mismatch
  • Folder filtering in Explorer
  • Query not including organization docs

Fixes:

  1. Check organization_id in .commander/config.json matches your Commander organization
  2. Clear Explorer filters - Click "All Documents"
  3. Refresh Commander - Hard refresh with Cmd+Shift+R

Authentication Errors

Symptoms: Sync fails with "unauthorized" or "401" errors.

Fixes:

  1. Verify API key:

    echo $WAYMAKER_API_KEY

    Should start with wm_ or be a valid service key.

  2. Check key hasn't expired - Generate new key in Waymaker One Settings

  3. Verify service key:

    echo $WAYMAKER_APPS_SERVICE_KEY

    Should be your service role key.

Frontmatter Parse Errors

Symptoms: Sync fails with YAML parsing errors.

Common mistakes:

# WRONG - missing indentation
---
sync:
type: task
---

# WRONG - missing space after colon
---
sync:
  type:task
---

# WRONG - incorrect delimiters
--
sync:
  type: task
--

# CORRECT
---
sync:
  type: task
---

Fix: Use exactly 2 spaces for indentation, space after colons.

Bidirectional Sync Not Working

Symptoms: IDE to Commander works, but Commander changes don't sync back.

Causes:

  • Mode set to ide-to-commander only
  • Missing taskboard_id in config
  • Real-time sync connection failed

Fixes:

  1. Check sync mode:

    "sync": {
  "mode": "bidirectional"
}

  2. Verify taskboard_id is set in .commander/config.json

  3. Check daemon startup logs for:

    • ✅ Commander → IDE sync started (Reverse Sync) — working
    • ⚠️ Reverse sync disabled (no taskboard_id configured) — fix config
    • ⚠️ Failed to start reverse sync — check error details

File Encoding Errors

Symptoms: Sync fails with encoding errors, corrupted characters (U+FFFD), or "invalid UTF-8" messages.

Causes:

  • File not saved as UTF-8
  • Copy-paste from Word, Google Docs, or PDFs
  • Windows-1252 or other legacy encodings

Characters to Watch:

  • Smart quotes: " " ' ' (curly quotes)
  • Em-dashes: — (long dash)
  • Ellipsis: … (single character)
  • Trademark symbols: ™ ® ©
  • Accented characters from non-UTF-8 sources

Diagnosis:

# Check file encoding
file --mime-encoding yourfile.md

# Find non-UTF-8 files in a directory
find . -name "*.md" -exec file --mime-encoding {} \; | grep -v utf-8

Fixes:

  1. Re-save as UTF-8 in your editor:

    • VS Code: Click encoding in status bar → "Save with Encoding" → "UTF-8"
    • Cursor: Same as VS Code

  2. Convert file:

    iconv -f WINDOWS-1252 -t UTF-8 badfile.md > goodfile.md

  3. Replace problem characters manually (search for � replacement character)

Sync Conflicts (Both Sides Edited)

Symptoms: .conflict.md file appears alongside your original file.

What happened: Both you (in IDE) and someone else (in Commander) edited the same task while the sync daemon was offline.

How it works:

  • The .conflict.md file contains YOUR local version
  • The main .md file contains the Commander version
  • You must manually resolve

Resolution:

  1. Open both files side by side
  2. Merge changes into the main file
  3. Delete the .conflict.md file
  4. Save — sync will push the merged version

Example:

docs/02-working/tasks/backlog/my-task.md           # Commander version
docs/02-working/tasks/backlog/my-task.conflict.md  # Your local version

Prevention: Keep the sync daemon running when actively collaborating.

Duplicate Documents

Symptoms: Same file creates multiple documents in Commander.

Causes:

  • document_id not saved after first sync
  • Config reset

Fixes:

  1. Commit sync metadata:

    git add docs/
git commit -m "docs: update sync IDs"

  2. Don't delete auto-generated IDs from frontmatter:

    sync:
  type: task
  document_id: "abc123"  # Keep this!

Diagnostic Commands

Check MCP Server Status

waymaker_sync_status

View Recent Errors

The status output includes recentErrors array with last 10 errors.

Check Status File Directly

When the daemon is running, it writes status to .commander/sync-status.json:

cat .commander/sync-status.json

This file contains:

  • running: true/false
  • filesWatched: [number]
  • syncCount: [total syncs]
  • errorCount: [total errors]
  • recentErrors: [last 10 errors]
  • updatedAt: [timestamp]

If this file is missing or stale (>10 seconds old), the daemon may have crashed.

Test Configuration

waymaker_sync_configure action=validate

Error Reference

Quick lookup for common sync errors:

Error MessageCauseFix
401 UnauthorizedToken expired or invalidwaymaker auth login
CLERK_AUTH_FAILEDEdge function auth issueCheck API key, re-login
unique_markdown_name_per_workspaceDuplicate document nameClear .commander/sync-index.json, re-sync
unsupported Unicode escape sequenceNon-UTF-8 content in fileFix encoding
idx_unique_folder_nameFolder race conditionReduce --concurrency
Unhandled error in [file]File caused sync crashCheck file content, fix and retry
Token expired. Run waymaker auth loginOAuth token TTL exceededwaymaker auth login
No taskboard_id configuredMissing configRun waymaker init with taskboard
Reverse sync disabledMissing anon key or configCheck daemon startup logs
CONFLICT detectedBoth sides edited same fileResolve conflict

Getting More Help

Information to Include

When contacting support, include:

  1. Output of waymaker_sync_status
  2. Your .commander/config.json (redact sensitive IDs)
  3. Example file that won't sync (with frontmatter)
  4. Error messages from MCP server

Support Channels

Still stuck? Email support@waymakerone.com with diagnostic info.