From dbd42980c2f9aab4b265c25b7869fdedda2029f2 Mon Sep 17 00:00:00 2001
From: CREATIVE_tg1 <1+creative_tg1@noreply.localhost>
Date: Wed, 27 May 2026 14:58:14 +0000
Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D1=82?=
 =?UTF-8?q?=D1=8C=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8=D1=86=D1=83=20Tro?=
 =?UTF-8?q?ubleshooting=20=D0=B2=20wiki?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Troubleshooting.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 Troubleshooting.md

diff --git a/Troubleshooting.md b/Troubleshooting.md
new file mode 100644
index 0000000..467d3ab
--- /dev/null
+++ b/Troubleshooting.md
@@ -0,0 +1,88 @@
+# Диагностика и ошибки
+
+## Частые ошибки библиотеки
+
+### InvalidUrlError
+
+Причина:
+
+- ссылка не относится к YouTube
+- ссылка не начинается с `http://` или `https://`
+
+Что делать:
+
+- проверьте домен ссылки
+- проверьте схему URL
+
+### InvalidSessionError
+
+Причина:
+
+- cookie-файл не найден
+- cookie-файл не соответствует Netscape format
+- в файле нет YouTube или Google cookies
+- auth-cookie устарели или неполные
+
+Что делать:
+
+- проверьте путь к файлу
+- переэкспортируйте cookies
+- убедитесь, что экспорт выполнен из авторизованной YouTube-сессии
+
+### JsRuntimeUnavailableError
+
+Причина:
+
+- в системе нет Deno
+- в системе нет Node.js 22+
+
+Что делать:
+
+- установите Deno
+- либо установите Node.js версии 22 или выше
+
+### VideoDownloadError
+
+Причина:
+
+- yt-dlp не смог скачать ролик
+- yt-dlp вернул неожиданный формат метаданных
+- итоговый файл не оказался MP4
+
+Что делать:
+
+- проверьте актуальность cookies
+- проверьте доступность видео
+- убедитесь, что ffmpeg установлен, если нужен лучший формат объединения потоков
+
+## Частые вопросы по CI и публикации
+
+### Почему пакет не публикуется
+
+Причины:
+
+- CI запущен не на push в `main`
+- не настроены secrets для registry
+- текущая версия уже существует в Gitea Packages
+
+Что делать:
+
+- проверьте, что workflow идёт по push в `main`
+- проверьте `PYPI_REPOSITORY_URL`, `PACKAGE_USERNAME`, `PACKAGE_TOKEN`
+- увеличьте `project.version` в `pyproject.toml`
+
+### Почему старая версия не удаляется
+
+Это нормальное поведение. Публикация новой версии не удаляет старые версии пакета.
+
+### Почему публикация пропускается
+
+CI заранее проверяет, существует ли текущая версия в registry. Если версия уже опубликована, upload пропускается без падения workflow.
+
+## Практический чек-лист
+
+- обновите cookies
+- проверьте наличие Deno или Node.js 22+
+- проверьте наличие ffmpeg
+- проверьте `project.version` в `pyproject.toml`
+- проверьте secrets для Gitea Packages