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.

---

Commander Changes Don't Sync Back

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

Commander → IDE sync is not currently available. The watcher opens the real-time connection those changes would arrive on — its terminal logs Realtime disconnected and retries if that connection drops — but nothing on the platform sends changes down it yet. Edit in your IDE and let sync carry the change to Commander.

---

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)

---

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 Message	Cause	Fix
401 Unauthorized	API key missing, revoked or invalid	Set a current WAYMAKER_API_KEY — Authentication
CLERK_AUTH_FAILED	Edge function auth issue	Check API key, re-login
unique_markdown_name_per_workspace	Duplicate document name	Clear .commander/sync-index.json, re-sync
unsupported Unicode escape sequence	Non-UTF-8 content in file	Fix encoding
idx_unique_folder_name	Folder race condition	Reduce --concurrency
Unhandled error in [file]	File caused sync crash	Check file content, fix and retry

---

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

• Email: support@waymakerone.com
• X/Twitter: @stuartdotleo

---

Related Articles

• Getting Started with Waymaker Sync
• Frontmatter Reference
• Configure AI Assistants

---

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