Troubleshooting

Issues you may encounter with the Meldoc CLI.

Known errors

Error	Cause	Fix
command not found: meldoc	Binary not in PATH	See PATH not configured below
not in a git repository	Command run outside a git repo	cd to your repo root, or run git init
authentication failed	Token expired or invalid	Run meldoc auth login or update MELDOC_TOKEN
MELDOC_TOKEN not configured	No token set	Set MELDOC_TOKEN or run meldoc auth login
workspace not configured	Using meldoc auth login without workspaceAlias in config	Set workspaceAlias in meldoc.config.yml or run meldoc init
duplicate alias	Two files share the same alias	Edit frontmatter to assign unique aliases, then run meldoc validate
has no alias in frontmatter	Document missing alias field	Add alias: my-doc to frontmatter, or run meldoc migrate
invalid workflow/visibility/exposure	Unrecognized enum value	Use valid values — see Configuration for allowed fields
parentAlias equal to its own alias	Document references itself as parent	Change or remove parentAlias
Broken magic link [[alias]]	Link target doesn’t exist	Create the target document or fix the alias
failed to parse frontmatter	Invalid YAML	Check for duplicate keys or missing --- delimiters
conflict in <file>	Local and server both modified	Choose a resolution strategy with --resolve — see Conflict Resolution
already initialized	meldoc init run on initialized repo	Use --force to reinitialize
batch size N exceeds maximum of M	More docs than the server batch cap	Update the CLI to the latest version — meldoc pull auto-chunks in newer releases

Exit codes

Worth knowing when you wire the CLI into a script: a push or pull that ended in unresolved conflicts is not a failure, and it does not exit 1.

Code	Meaning
0	Success
1	Error
4	Finished, but with unresolved conflicts (push and pull only)

A document is not picked up

With baseDirs, a file is processed only if it sits inside one of the configured project directories. A file outside every baseDir belongs to no project and is ignored — silently, as far as a normal run is concerned.

meldoc ci --debug   # shows which paths were routed where, and which were ignored
meldoc docs         # lists each project's tree in turn

Two things look like the fix and are not:

• patterns cannot widen a project’s boundary. They select documents within a project, so a pattern as broad as \.md$ still sees only what is under that project’s baseDir.
• A sibling directory with a shared prefix is a different directory. handbook-old is not inside handbook — paths are compared segment by segment, not as text.

The fix is to move the file into a project’s directory, or to add a project for it. See Several Projects in One Repository.

This applies to baseDirs only. A config with a single baseDir still scans the whole checkout: in that older form, baseDir says where new documents are put, not where the project ends.

PATH not configured

If your terminal can’t find meldoc after installation, the install directory isn’t in your PATH.

Unix (macOS/Linux):

# Reload shell config
source ~/.zshrc   # zsh
source ~/.bashrc  # bash

# Or add manually
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Windows:

meldoc setup-path

Then restart your terminal.

Setup wizard didn’t run

When installed via pipe (curl … | bash), the setup wizard can’t run in a non-interactive context. The installer prints a command at the end. Open a new terminal and run it:

~/.local/bin/meldoc setup

If meldoc is already in your PATH:

meldoc setup

Debug mode

Add --debug to any command for verbose logging:

meldoc push --debug
meldoc pull --debug
meldoc mcp doctor --debug

Capture output to a file:

meldoc push --debug 2>&1 | tee debug.log

Inspect state

Check sync status, cache, and authentication when something looks off:

meldoc scan
meldoc validate
meldoc auth status
meldoc mcp doctor

Check raw cache files:

cat .meldoc/cache/state.json
cat .meldoc/cache/cursor.json
cat meldoc.config.yml

Reset cache

Clear the local cache without affecting your config or files:

meldoc cache clear

Then rebuild with meldoc scan --force or meldoc push --force.

Reset cursor

If incremental pulls return stale data, delete the cursor file and pull again:

rm .meldoc/cache/cursor.json
meldoc pull

Full reset

If nothing else works, remove the entire .meldoc/ directory and start fresh:

rm -rf .meldoc/
meldoc init --force
meldoc pull --force

This preserves your config file and local .meldoc.md files.

One project fails, the others do not

A failure in one project neither stops nor rolls back the rest. The run finishes the remaining projects, exits non-zero, and ends by naming both groups:

Processed: meldoc-app
Not processed: meldoc-public-app

Everything listed as processed is synchronised and cached, so re-running retries only what actually changed. --project retries the failed one on its own.

Overriding the API endpoint

Point the CLI at a different server when you need to see what it is really talking to:

export MELDOC_SERVER="https://api.meldoc.io"
meldoc push --debug

Automating the checks

Catching a broken document before it is committed costs less than finding it in a pipeline.

#!/bin/sh
# .git/hooks/pre-commit
meldoc validate || {
  echo "meldoc validate failed. Fix the errors before committing."
  exit 1
}

#!/bin/sh
# .git/hooks/post-merge
meldoc pull --yes

The same three as Make targets:

docs-push:
	meldoc validate && meldoc push

docs-pull:
	meldoc pull --yes

docs-check:
	meldoc scan && meldoc validate

What’s next?

Conflict Resolution — Resolve sync conflicts between local and server edits.

Command Reference — Full reference for every CLI command and flag.

Environment Variables — Token priority and all environment variables.