Troubleshooting

Authentication fails

Symptoms:

• CLI prints auth_expired
• API returns 401 unauthorized
• opendocs whoami fails

Fix:

opendocs login --key od_live_xxxxx
opendocs whoami --json

If the key was revoked or lost, create a new one in Dashboard -> API Keys. Agents and CI should pass --key or set OPENDOCS_API_KEY; bare opendocs login waits for an interactive prompt.

Publishing goes to the wrong workspace

The CLI stores one active workspace locally. Check it:

opendocs whoami --json
opendocs workspace list --json

Switch if needed:

opendocs workspace use acme-docs --json

The dashboard's active workspace is independent of the CLI's active workspace.

A public URL returns 404

Check these in order:

1. The post is still published: opendocs get <slug> --json.
2. The post visibility is public.
3. The workspace has Allow public documents enabled in Dashboard -> Workspace settings.

To change a post to public:

opendocs visibility launch-note public --confirm-public

If you only meant team sharing, use workspace visibility instead.

Free document limit

Free workspaces can have 10 currently published documents. If a publish fails with document_limit, the fix is one of:

• unpublish a document you no longer need
• publish fewer files
• upgrade to Pro

Unpublish frees a slot:

opendocs list --json
opendocs unpublish old-draft

Updates do not consume additional slots.

Export failures

Symptoms:

• export_failed
• converter_timeout
• a publish succeeded but --export pdf failed

The published post usually still exists. Retry export only:

opendocs export report --format pdf --json

If DOCX export fails on Free, upgrade to Pro or export PDF instead. Free PDF exports include the OpenDocs footer and default branding.

Batch publish partially failed

Batch publish can succeed for some files and fail for others. In --json, read the results array:

{
  "total": 10,
  "succeeded": 9,
  "failed": 1,
  "results": [
    { "success": false, "file": "duplicate.md", "error": "publish_failed" }
  ]
}

Fix the failed files and re-run only those files. Keep the same shared tag so the group stays discoverable.

Local images do not render

The CLI uploads local Markdown images before publish. Check:

• the image path exists
• the image is inside the Markdown file's directory
• the image is JPEG, PNG, WebP, GIF, or SVG
• the image is 10 MB or smaller

Remote image URLs are left as-is.

Rate limits

If the API returns 429 rate_limited, wait at least a minute before retrying. Do not put agents in tight retry loops.

Common buckets:

Route group	Limit
General API traffic	120 requests / minute
Single publish	30 requests / minute
Batch publish	5 requests / minute
Single export	20 requests / minute
Batch export	3 requests / minute