Skip to content
Tarkle Docs

Troubleshoot the MCP server

The errors and symptoms an AI assistant or script sees with the Tarkle MCP server, with the cause and the fix for each.

When a call to the MCP server fails, the answer says why. This page lists each error, what causes it and how to fix it. Find the status or the code, then follow the fix.

A tool that fails returns text that starts with the code, a colon and a short message, for example FILE_TOO_LARGE: This file is larger than your plan's per-file limit.. The result is marked as an error. A failure before a tool runs returns an HTTP status with a short JSON body.

Connection errors

401 unauthorized

The server answers with status 401, the body {"error":"unauthorized"} and a WWW-Authenticate header when it cannot match the credential to an active account. The usual causes are:

  • The Authorization header is missing or does not read Authorization: Bearer <your-tarkle-key>.
  • The key was deleted. A deleted key stops working at once.
  • The key was made before full access was added to keys. It shows the Legacy badge in Settings, API. The MCP server does not accept these keys, so the call gets 401 and not a tool error.
  • The account that made the key is suspended.

Fix: check the header first. If the key has no Legacy badge, copy it again from Settings, API. An owner or admin can copy a key again. A Legacy key has no copy. For a deleted or Legacy key, create a new key in Settings, API and put it in place of the old one. For ChatGPT, Claude and Grok, which connect by browser sign-in, reconnect the connector and sign in again.

404 MCP_DISABLED

The body is {"error":"MCP_DISABLED"}. The server returns this for every request when Tarkle has switched it off. It also returns this after a valid sign-in when the partner that manages the account has switched AI connectors off for that account.

Fix: if the server is off, try again later. If your partner manages the account, ask them to turn AI connectors on.

429 rate_limited

The limit is counted per person and per minute. Read calls get 120 a minute. Calls that start an upload, get more upload addresses, create a public link or create a file request share a bucket of 30 a minute. Failed sign-in attempts from one address are limited to 30 a minute.

Fix: wait for the number of seconds in the Retry-After header, which every 429 carries, and then send the call again.

Tool errors

NOT_FOUND: Workspace not found.

The workspace does not exist for this person, or the person has no access to it. The server answers Workspace not found. in both cases. A key limited to chosen workspaces gets the same answer for a workspace outside its list. A key limited to chosen workspaces also sees only those workspaces in tarkle_list_workspaces.

Fix: call tarkle_list_workspaces and use a workspaceId from that list. If the workspace is missing from the list, the person behind the key must be a member of it. For a key limited to chosen workspaces, create a new key that includes that workspace.

FORBIDDEN: Your role in this workspace cannot upload or share files.

The person’s role in the workspace does not allow uploads, public links or file requests. tarkle_list_workspaces marks such workspaces with cannot upload or share.

Fix: ask an owner or admin of the workspace to change the person’s role, or use a workspace where the role allows it.

FORBIDDEN: This workspace is suspended.

The workspace is suspended, so the server refuses it for every tool.

Fix: contact Tarkle support. The FAQ explains how to reach it.

FORBIDDEN: This key is limited to selected workspaces and cannot create a workspace.

A key limited to chosen workspaces cannot make a new workspace, because the new one would not be in its list.

Fix: create the workspace in the Tarkle app, or use a key that reaches every workspace of the organization to call tarkle_create_workspace.

Confirmation required (not an error)

Tools that publish or change people, such as public links, file requests, invites, member changes and new workspaces, do nothing on the first call. The reply starts with Nothing was created yet. This will and includes a confirmationCode.

Fix: Show the preview to the person and ask whether to go ahead. After they say yes, call the same tool again with exactly the same inputs and the confirmationCode. The code works for 10 to 20 minutes and only for those inputs. If you change any input, or the code is too old, the tool answers again with a new code.

CLIENT_SIZE_LIMIT

Tarkle sets the class of a browser sign-in client from the return addresses it registers. A client whose return address is a web address that is not on this computer is a chat app. A chat app that asks for a file above 5 GB gets the message This app can send files up to 5 GB through Tarkle. from tarkle_start_upload. A key is treated as an assistant that runs on the person’s computer, so a key does not get this error.

Fix: call tarkle_get_upload_page and ask the person to choose the file in the browser. The browser upload follows the plan limit. Or use an assistant on the person’s computer, or the Tarkle API with a key.

FILE_TOO_LARGE: The file is bigger than the per-file limit of the organization’s plan.

Free supports uploads and transfers up to 1 GB each. Pro and Agency support files up to 200 GB.

Fix: upload a smaller file, or change the organization’s plan on the pricing page.

STORAGE_LIMIT_EXCEEDED: The files already stored, plus the uploads still in progress, plus this file, are more than the storage of the plan.

Reaching a limit does not delete existing files.

Fix: free up space or upgrade the organization’s plan. Deleting files in the Tarkle app frees space.

TOO_MANY_OPEN_UPLOADS

The message is Too many uploads are open. Finish or wait for existing ones to expire. Many upload sessions are open at once.

Fix: finish the open uploads, or wait until they expire, then start the next one.

SESSION_EXPIRED: This upload session has expired or is already finished.

An upload session lasts 24 hours. The error also comes back for a session that already finished, failed or was stopped.

Fix: Start a new upload with tarkle_start_upload.

Upload addresses expire after one hour

The addresses that tarkle_start_upload returns are signed for one hour, so a part sent after that needs a fresh address.

Fix: call tarkle_get_upload_parts with the sessionId and the number of the first part still to send. It returns fresh addresses for the parts that are left. Retry a part whose address expired with the same call.

SIZE_MISMATCH: The uploaded size does not match what was declared.

The bytes that arrived are not the sizeBytes the upload declared. For a file split into parts, each part must have the exact length the server returned in contentLength for it.

Fix: start a new upload with the exact size of the file, and send every part with its own contentLength.

Upload status: Waiting for the file bytes

tarkle_get_upload_status answers with the number of parts received and Waiting for the file bytes. That means not every part has arrived.

Fix: send the parts that are missing. tarkle_get_upload_status is safe to call again and again. When every part has arrived, it finishes the upload and returns a fileId.

Text and address uploads

tarkle_upload_text takes up to 3 MB of text. A larger text answers CONTENT_TOO_LARGE. tarkle_upload_from_url takes a file up to 50 MB from a public https address. A larger file answers FILE_TOO_LARGE_FOR_URL.

If the address cannot be downloaded, the tool answers URL_FETCH_FAILED with the message Tarkle could not download that address. It may need a sign-in, be private, or have expired. The address must be a public https address.

Fix: save text that is smaller, use a public address that opens without a sign-in, or call tarkle_get_upload_page for a larger file.

ENTITLEMENT_UNRESOLVED and STORAGE_USAGE_UNREADABLE

Tarkle could not confirm this workspace’s plan right now, or it could not total the stored files of the workspace. The upload is not started, and the message asks you to try again shortly or to contact support.

Fix: wait a few minutes and try again. If it still fails, contact Tarkle support.

ERROR: The request could not be completed.

The server returns this for a failure that has no more specific code.

Fix: retry the call once. If it happens again, contact Tarkle support with the tool name and the time of the call.

Frequently asked questions

Which assistants work with the MCP server?

ChatGPT, Claude and Grok connect by browser sign-in, with no key. Claude Code, Codex, Cursor, VS Code (GitHub Copilot) and Windsurf use an API key sent as Authorization: Bearer <your-tarkle-key>. Any other client that supports remote MCP servers with custom headers can use the key the same way. The setup for each client is on /mcp/connect.

Does it cost extra?

The MCP server is on for every account. Uploads made through it use the storage and the per-file limit of the organization’s plan. An API key cannot make purchases.

Can it delete my files?

No tool deletes a file or a folder. The tools that remove something are tarkle_delete_file_request, which deletes a file request and its link and keeps the files submitted to it, and the member-removal tools, which take a person out of the workspace or a team folder. The full list is on /mcp/tools.

Where do I revoke access?

For a key, open Settings, API and delete the key. Deleting stops the key at once. For ChatGPT, Claude or Grok, no key is stored in Tarkle, so remove the connector in that app to stop it.

How do I report a problem?

Use the Support link in your dashboard, or email support@tarkle.com. The contact article lists what to include. Send the error code, the tool name and the time of the call.

Tarkle Docs

Type to search…

↑↓ navigate↵ selectEsc close