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