Troubleshooting

Use this guide to diagnose document access, version conflicts, and rendering problems.

Document access is denied

Check that the URL still contains the correct share key and that the link has not been revoked. If you are using an account document, sign in with the owning mere.world account.

A view link cannot edit, and a comment link cannot create suggestions.

A write returns 409

Your write was based on an older document version.

1. Read the current Markdown.
2. Reapply the intended change.
3. Send the new version with If-Match or baseVersion.

Do not discard the current source or force the old copy unless that replacement is deliberate.

Live and Source look different

Live mode renders Markdown and supported fences. Source mode shows exact text. If a block renders unexpectedly, inspect its fence and closing delimiter in Source mode.

Uploaded media does not render

Confirm that:

• The upload completed
• The Markdown URL points to the returned /f/ asset
• The current share or account can access the document
• The file uses a supported content type

CLI command is missing

To list supported CLI commands, run this command:

agmd commands --json

Update the installed executable from the verified site installer if it is older than the production manifest.

CLI cannot find a command

Make sure ${HOME}/.local/bin is on PATH, or set AGMD_BIN_DIR during install.

The CLI requires Node.js 20 or later.

An agent overwrote another edit

Restore the appropriate revision, then move the agent to version-aware writes. Give proposal-only agents suggest access.

Node media is unavailable

For missing media controls, see Node troubleshooting.

Service health

To check database and service configuration, run this command:

curl -fsS https://agentsmarkdown.com/api/health

When reporting a problem, include the route, status code, response request identifier if present, and the minimal reproducible operation. Remove document keys and tokens.