---
title: "rclone with Tarkle: limits and common errors (beta)"
description: "Beta rclone with Tarkle: what sync, large files and rate limits do, what rclone cannot do, and how to fix the common errors."
canonical: "https://tarkle.com/help/apps-and-developers/rclone-with-tarkle-limits-and-errors"
last-updated: 2026-11-04
---

# rclone with Tarkle (beta): limits and how to fix common errors

What rclone can and cannot do with Tarkle, and how to fix the errors you are most likely to see.

This article covers what rclone can and cannot do with Tarkle, then the errors you may see and how to fix them.

**Beta:** the rclone support for Tarkle is in beta. It is not in any official rclone release, so `rclone config` on a normal rclone install does not show Tarkle. You build rclone from Tarkle's fork instead. Build it only if you are comfortable with Go and a terminal. The Tarkle rclone support is also proposed to rclone in [pull request 10250](https://github.com/rclone/rclone/pull/10250). Until it is in an official release, it works only with a build from the fork.

## Build rclone with Tarkle support

1. Clone the fork with `git clone https://github.com/tarkleHQ/rclone`, then open it with `cd rclone`.
2. Switch to the branch that holds the Tarkle support: `git checkout tarkle-backend`.
3. Build the binary with `go build -o rclone-tarkle .`. The build needs Go 1.26. The commands below use `./rclone-tarkle`, not the rclone you installed before.

## Connect rclone to your workspace

You need an API key. [How to create and manage an API key](https://tarkle.com/help/apps-and-developers/how-to-create-and-manage-an-api-key) explains every choice, and the steps below cover what rclone asks for.

1. Owners and admins of your organization open [API](/dashboard/settings/api) in Settings and stay on the **API keys** tab. Click **Create**, type a **Name**, and under **Access** choose **All workspaces** or **Only selected workspaces**. Click **Create**, click the key to copy it, then click **Done**. Members ask an owner or admin for a key, as explained in [Teams, roles and sharing files with your team](https://tarkle.com/help/team-and-clients/teams-roles-and-sharing-files-with-your-team).
2. Run `./rclone-tarkle config`, type `n` for a new remote, and name it `tarkle`. At the storage prompt, type `tarkle`.
3. At **token**, paste the key. rclone stores it obscured.
4. At **workspace**, type the 8-character workspace key. This setting is required, because one key can reach several workspaces. If you leave it blank, the first command that uses the remote stops and lists the workspace keys and names to choose from.
5. Answer `n` to **Edit advanced config?**, then confirm the remote with `y`.
6. Run `./rclone-tarkle lsf tarkle:` to list the top level of your library.

## What rclone can do with Tarkle

`rclone sync` and `rclone check` work without `--size-only`. Tarkle stores the modification time to one second and a SHA-256 for each file. For files up to 100 MiB, Tarkle checks the stored file against the SHA-256 when it is uploaded.

Large files upload as parallel parts straight to storage, so they do not pass through the API. Free accepts files up to 1 GB each, and Pro and Agency accept files up to 200 GB (see [pricing](/pricing)).

rclone overwrites a file with the same name. On plans that keep file versions, the new content becomes a new version, as [file versioning](https://tarkle.com/help/storage/file-versioning-what-it-is-and-how-it-works) explains. On other plans, the old file is replaced once the new one has uploaded.

## What rclone cannot do with Tarkle

- **Upload a stream of unknown size.** rclone needs the size first, so it saves a stream to a temporary file before it uploads.
- **Keep other metadata.** Tarkle keeps the modification time and the creation time, and the creation time is read only.
- **Change protected folders.** System folders, the folder of an active file request, team folders and folders of active transfers can be read, but a rename, move or delete is refused with a 403 error.
- **Use a name longer than 255 bytes** in UTF-8.
- **Delete a file in an active transfer** unless you add `--tarkle-delete-transfers`, which also deletes the transfers that contain it. Feedback boards and paid transfers with purchases can never be deleted this way.
- **Delete into the bin.** Deleting a file or folder moves it to the Tarkle bin, where it stays for as long as the plan's bin retention allows.

## Fix common errors

Each heading is the message rclone prints.

- **Tarkle is not in the storage list.** A normal rclone install does not include Tarkle. Build the binary from the fork as shown above, and run `./rclone-tarkle`.
- **401 unauthorized: "This token is invalid or has been revoked".** The key is mistyped or was deleted. Owners and admins can copy a key again from its row menu with **Copy token**, or create a new key.
- **401 legacy_token.** The key is an older workspace key that no longer works. Create a new key in Settings, API, then edit the remote with `./rclone-tarkle config`.
- **403 no_access.** The workspace key is wrong, or the key cannot reach that workspace. Check the workspace key first. A key set to **Only selected workspaces** reaches only the workspaces ticked when it was made, so create a new key that includes this workspace. The person who made the key must still have access to the workspace too.
- **403 forbidden, with a message about a missing scope.** A key with the **Legacy** badge in Settings, API was made before API keys had full access, and keeps its old, limited permissions. Create a new key for full access.
- **413 file_too_large.** The file is larger than your plan allows. Check the limit for your plan, then move the file or use a plan with a larger limit.
- **413 storage_limit_exceeded.** The workspace has no room left for the file. Free up space in the workspace, then run the command again.
- **429 rate_limited.** The files API allows 600 requests a minute for each key, and rclone retries on its own. If it keeps happening, add `--tpslimit` to the command, or lower `--transfers` and `--checkers`.
- **Delete refused: "item is in an active transfer".** Add `--tarkle-delete-transfers` to the same command.

## What happens next

Use the same remote with `rclone copy`, `rclone sync` and `rclone check` in your scripts. For example, `rclone copy /path/to/folder tarkle:backup` uploads a local folder to a Tarkle folder called backup.

## Related articles

- [How to upload and manage files with the Tarkle API](https://tarkle.com/help/apps-and-developers/how-to-upload-and-manage-files-with-the-tarkle-api)
- [What is the Tarkle API?](https://tarkle.com/help/apps-and-developers/what-is-the-tarkle-api)

Source: https://tarkle.com/help/apps-and-developers/rclone-with-tarkle-limits-and-errors