Documents & filesYandex Disk

Yandex Disk CLI troubleshooting

Fix a refused Yandex token, a folder that does not sync or a search that finds nothing.

A sign-in that fails, a sync that stops, a search that finds nothing: find your symptom here and fix it in a minute or two. Every error says what to do in its message, and its exit code tells a script what kind of failure it was.

On this page:

  1. First check
  2. By symptom
  3. Exit codes
  4. If it still fails

First check

ydisk doctor
ydisk personal doctor --online

doctor reads no keyring and uses no network. It shows what is set up and any problem with the settings file. doctor --online also asks Yandex whether the profile's token works.

By symptom

SymptomWhat to do
ydisk is not foundOpen a new terminal, and check that npm's global folder is on PATH.
"name a profile"Put the profile first, as in ydisk personal status, or set YDISK_PROFILE.
"refused the token", exit code 4The token is wrong, revoked or expired. Get a new token and run ydisk personal session start again.
A change fails with exit code 5The token has no cloud_api:disk.write right, or the profile's permissions or YDISK_READ_ONLY refuse it. Check settings. For the right, register the app again with it and get a new token.
"the OS keyring did not answer" on LinuxThe session bus restarted. Log out and back in, or sign in with session start --credential-storage file.
"no such item, or this token cannot see it", exit code 6Check the path with files list --folder on its parent folder. A Disk path starts with /, as in /Documents/plan.pdf.
"asked to slow down", exit code 8Yandex received too many requests from this account. Wait a minute and run the command again.
A sync stops before the endOne sync reads up to 200 files. Run sync again until status shows no pending work.
A chosen folder's documents are goneThe folder was renamed or moved on the Disk. Add it again under its new path with folders add.
Search does not find a file you know is thereSee when search finds nothing.
A PDF is found by name but not by its textIt is a scan with no text layer, or larger than 50 MB. status lists such files with the reason.
An upload fails because the Disk is fullFree space on the Disk or empty its trash. A retry does not help until there is room.
A large upload is refusedYandex limits one file's size by plan: 1 GB without a Yandex 360 plan, more with one (Yandex's limits).
A change ended with "outcome_unknown", exit code 14Yandex failed during the change, so it may or may not have happened. Check with files show before you run it again.
An agent changed a file you did not want changedOver MCP the ask level lets a command run. Deny files.delete and files.share, or set YDISK_READ_ONLY=1. See connect your agent. A deleted file is in the Disk's trash: files restore.
The settings file does not readdoctor lists every problem in the file under config.issues. Run the config unset each one gives, config repair, or fix the file by hand.
doctor lists files.problemsOther users of the computer can read config.json or enter its folder. Run each chmod that doctor prints after "to make it private:".

Exit codes

CodeMeaning
2The command was given wrong: a missing profile, argument or option.
3The settings or the keyring are not usable.
4Yandex refused the token.
5Not allowed: the token's rights or the profile's permissions.
6No such file or folder, or the token cannot see it.
7A change needs your confirmation and there was no terminal to ask.
8Yandex asked to slow down.
14A change may or may not have happened.

Every code is in the command reference.

If it still fails

ydisk runs list shows the recent runs, and ydisk runs show one of them with every step it took. Secrets are hidden. ydisk doctor reports create writes a report file for a bug report and says what it holds. Open an issue at github.com/WireCatLabs/ydisk-cli/issues with the error code and the command. Never paste a token or private content into an issue.