Troubleshooting

"Pro plan required" — but my token works

This is the most misdiagnosed error in MDflow.

A 403 Pro plan required means the credential is fine — the account is not on Pro (see 04 Free and Pro Plans). Creating a new token will not help, because the token was never the problem.

Everything that authenticates with a Personal Access Token requires Pro: the HTTP API, both MCP servers, the Web Clipper, the VS Code and Cursor extension, and the n8n node.

The exception: the iOS app, which is not Pro-gated at all.

401 on the API or MCP

The bearer credential is invalid, expired, or revoked. Create a new token at mdflow.cz/settings (see 01 Personal Access Tokens), or re-authorize the OAuth connection.

Distinguish it from 403 above: 401 is about the credential, 403 is about the plan.

429 — rate limited

You have passed 60 requests per minute. The response carries Retry-After, in seconds.

The limit is per token and per user, so more tokens will not help. If you are looping over many items — especially in n8n, which does not retry — add a delay or handle the error.

My agent created folders in the wrong workspace

Almost certainly this: mdflow_create_folder takes workspace_id, not workspaceId — see 03 MCP Servers.

Passing the camelCase spelling does not fail. The parameter is dropped and the folder is created in your oldest workspace — quietly, with a success response.

Check the workspace_id in the response before creating documents underneath. (mdflow_list_folders accepts both spellings, which is what makes this easy to get wrong.)

Note that mdflow_move_folder cannot fix it — it only reparents within a workspace. Move the folder in the web app, or delete and recreate.

My encrypted document doesn't appear in search

Working as designed. The server stores only ciphertext, so there is nothing to index. Encrypted documents are excluded from workspace search, from Knowledgebase collection search, and are skipped by the Tasks view.

This is the encryption guarantee (see 01 Document Encryption), not a bug. If you need it searchable, remove the encryption.

I lost an encrypted document's password

It cannot be recovered. Not by you, not by support, not by MDflow. The key is derived from the password (see 01 Document Encryption) and exists nowhere else.

My draft disappeared

If the server copy changed while you had an unsaved local draft — you edited on another machine, or an agent updated the document — the stale draft is discarded rather than restored, to avoid overwriting newer content.

On Pro, check version history for the text.

Version history is empty or gone

Either the account is on Free (which accrues no history), or it returned to Free, which removes existing history. Your documents are untouched; only the history goes. See 06 Version History.

Also note: history covers the body only. Renames and moves are not recorded.

My AI agent can't read version history

By design. History is private to the owner and is not exposed through the API or the MCP server. An agent can overwrite a document but never see what was there.

That asymmetry is the point — history is your recourse when an agent gets it wrong.

I can't upload an image

• On mobile: image upload is desktop only. Mobile can view images, not add them. The iOS app has no image support at all.
• On an encrypted document: images cannot be added while a document is encrypted, and encrypting removes existing ones. Use an externally hosted image by URL.
• Over quota: Free allows 5 images.
• Wrong format: JPEG, PNG and WebP only (see 04 Images).

GitHub or Google Drive says the file changed

Someone edited it at the source since you opened it. MDflow never overwrites silently — you choose whether to reload the latest version.

Note the VS Code extension behaves differently: it is last-write-wins with no conflict detection.

My custom domain isn't working

DNS takes time to propagate. Settings shows the connection status while it does — use it to tell "not yet" from "misconfigured". Check the DNS records match exactly what MDflow displayed.

I can't delete my last workspace

Intentional. The last remaining workspace cannot be deleted, so you always have somewhere to write. Create another first if you really want to remove that one.

The Web Clipper stopped working

• Token invalid? Create a new one; it may have been revoked.
• Folder gone? The destination was deleted or moved — pick a new one.
• Cleared browser data? The clipper stores its token, templates, properties and highlights locally. Clearing browser data wipes the lot. Re-paste the token (see 02 Connecting to MDflow) and import your settings export.
• Not an http/https page? Local files and browser pages cannot be clipped.

I deleted something by accident

There is no trash, no soft delete, and no restore. Deletions are immediate and permanent — documents, folders, workspaces, and images.

The exception: Google Drive deletions go to Drive's Trash, because they are Drive's files.

If it was a document body change rather than a deletion, and you are on Pro, version history has it.

Nothing here matches

Support is linked from Settings.