From 848a9e79e74dcb3e5f74f13876c66fafabc982e5 Mon Sep 17 00:00:00 2001
From: Liremant <mail.liremant@gmail.com>
Date: Thu, 30 Oct 2025 00:22:53 +0800
Subject: [PATCH 1/5] docs(common-issues): add troubleshooting guide

---
 docs/common-issues.md | 250 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 250 insertions(+)
 create mode 100644 docs/common-issues.md

diff --git a/docs/common-issues.md b/docs/common-issues.md
new file mode 100644
index 00000000..05362788
--- /dev/null
+++ b/docs/common-issues.md
@@ -0,0 +1,250 @@
+# Устранение неполадок (Troubleshooting)
+
+В этом разделе собраны часто встречающиеся проблемы при эксплуатации панели Remnawave, признаки их проявления и пошаговые инструкции по диагностике и устранению. Для каждой проблемы указаны симптомы, вероятные причины и практические проверки.
+
+---
+
+## 502 Bad Gateway на странице подписки
+
+### Симптомы
+
+- При переходе на домен страницы подписки возвращается 502 Bad Gateway.
+- Ссылки на страницу подписки не работают или возвращают ошибку сервера.
+
+### Частые причины и шаги решения
+
+1. Неправильный путь URL
+   - Проблема: Вы открываете корневой домен без UUID подписки.
+   - Решение: Используйте формат:
+```
+https://sub.example.com/<shortUuid>
+```
+
+2. Конфигурация реверс-прокси
+   - Проблема: Прокси не перенаправляет запросы на контейнер страницы подписки.
+   - Решение: Убедитесь, что прокси направляет трафик на `remnawave-subscription-page:3010`.
+   - Проверка: Посмотрите логи контейнера страницы подписки:
+```bash
+docker compose logs -t -f
+```
+
+3. Переменные окружения
+   - Проверьте значение `SUB_PUBLIC_DOMAIN` в `.env` панели.
+   - После правки перезапустите контейнер панели.
+
+4. Общие проверки при 502
+   - Убедитесь, что DNS указывает на правильный IP.
+   - Проверьте доступность контейнера/бэкенда подписки.
+   - Проверьте таймауты в конфигурации реверс-прокси.
+   - Проверьте правила файрвола/WAF.
+
+---
+
+## "timeout of 45000ms exceeded" в панели
+
+### Симптомы
+
+- В интерфейсе панели появляется сообщение об ошибке таймаута при операциях с нодами (например, при получении статуса или управлении).
+
+### Частые причины и шаги решения
+
+1. Неправильная конфигурация порта ноды
+   - Проблема: Панель не может подключиться к REST API ноды по указанному порту.
+   - Решение: Убедитесь, что значение `Node Port` на ноде совпадает с портом, который использовался при генерации docker-compose для панели.
+   - Проверка: С хоста панели проверьте доступность порта ноды (telnet/curl).
+
+2. Сетевые проблемы
+   - Проблема: Блокировки/высокая задержка между панелью и нодой.
+   - Решение: Обеспечьте стабильное сетевое соединение; по возможности разместите ноду на сервере с надёжным каналом.
+   - Опция: Для сложных топологий рассмотрите Cloudflare Tunnel.
+
+3. Конфигурация ноды
+   - Проверьте соответствие переменных окружения ноды настройкам панели.
+   - Просмотрите логи контейнера ноды:
+```bash
+docker compose logs -t -f
+```
+   - Убедитесь, что нода запустилась без ошибок привязки портов.
+
+### Чеклист (короткий)
+
+- [ ] В профиле пользователя выбран активный сквад.
+- [ ] Внутреннему скваду назначены инбаунды.
+- [ ] Есть минимум один хост и он включён.
+- [ ] Хост привязан к инбаунду, выданному скваду.
+
+---
+
+## 502 после обновления панели
+
+### Симптомы
+
+- После обновления панели часть запросов возвращает 502.
+
+### Решения
+
+1. Перезапуск сервисов
+   - Следуйте разделу Upgrading в документации.
+   - Перезапустите панель и зависимые сервисы.
+   - Убедитесь, что контейнеры используют обновлённые образы.
+
+2. Реверс-прокси
+   - Если прокси работает отдельно, перезапустите его.
+   - Проверьте, что его конфигурация по-прежнему указывает на правильные контейнеры/сети.
+
+---
+
+## Telegram OAuth: "domain invalid"
+
+### Симптомы
+
+- При попытке авторизации через Telegram появляется "domain invalid".
+- OAuth не проходит валидацию.
+
+### Решение
+
+1. Настройка домена в BotFather
+   - Откройте @BotFather → Bot Settings → Domain.
+   - Укажите домен панели, например:
+     ```
+     https://panel.domain.com
+     ```
+   - Сохраните настройки в панели: Settings → Telegram.
+
+2. Ограничения Telegram
+   - Важно: OAuth Telegram не поддерживает домены в зоне `.xyz`. Используйте `.com`, `.net`, `.org` и т.д.
+   - Неправильный домен приведёт к сбою верификации OAuth.
+
+---
+
+## ECONNREFUSED после переустановки ноды
+
+### Симптомы
+
+- Панель не может подключиться к ноде; в логах — ECONNREFUSED.
+
+### Решения
+
+1. Проверьте переменные окружения
+   - Убедитесь, что параметры ноды соответствуют тем, которые сгенерировала панель.
+   - Подтвердите корректность `Node Port`.
+
+2. Перезапуск и проверка ноды
+   - Перезапустите ноду:
+     ```bash
+     docker compose down && docker compose up -d
+     ```
+   - Просмотрите логи:
+     ```bash
+     docker compose logs -f -t
+     ```
+   - Убедитесь в отсутствии ошибок привязки портов и в доступности порта.
+
+3. Конфигурация URL панели
+   - Проверьте `REMNAWAVE_PANEL_URL` для страницы подписки — он должен указывать на достижимый домен панели или внутренний сервис.
+
+---
+
+## Ошибки collation после обновления PostgreSQL
+
+### Симптомы
+
+- После мажорного обновления PostgreSQL возникают ошибки, связанные с collation базы данных.
+
+### Решение (rescue CLI)
+
+1. Откройте контейнер панели:
+```bash
+docker exec -it remnawave remnawave
+```
+2. В rescue CLI выполните действие:
+```
+● Fix Collation (Fix Collation issues for current database)
+```
+3. Перезапустите панель:
+```bash
+docker compose down && docker compose up -d
+```
+
+Примечание: такие ошибки чаще появляются при смене мажорной версии PostgreSQL, когда collations старой БД не совпадают с требуемыми новой версии.
+
+---
+
+## Ключевые переменные окружения
+
+Конфигурация панели:
+
+```bash
+# Домен панели для CORS/UI
+FRONT_END_DOMAIN=panel.yourdomain.com
+
+# Публичный URL страницы подписки
+SUB_PUBLIC_DOMAIN=sub.yourdomain.com
+# или для bundled-установки:
+# SUB_PUBLIC_DOMAIN=panel.yourdomain.com/api/sub
+```
+
+Страница подписки:
+
+```bash
+# Кастомный префикс подписки (опционально)
+CUSTOM_SUB_PREFIX=/custom-path
+
+# URL панели для доступа к API
+REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
+```
+
+Дополнительные опции:
+
+```bash
+# Включить документацию API
+IS_DOCS_ENABLED=true
+SWAGGER_PATH=/swagger
+SCALAR_PATH=/scalar
+
+# Метрики Prometheus
+METRICS_USER=admin
+METRICS_PASS=password
+```
+
+Важно: После изменения переменных окружения перезапускайте соответствующие сервисы.
+
+---
+
+## Быстрый диагностический чек-лист
+
+При 502:
+- [ ] DNS резолвится в правильный IP.
+- [ ] Контейнер бэкенда запущен.
+- [ ] Конфигурация реверс-прокси корректна.
+- [ ] Сервис доступен по правильному пути (домен vs подпуть).
+- [ ] Таймауты прокси настроены адекватно.
+- [ ] Переменные окружения установлены верно.
+- [ ] Сервисы перезапущены после изменений.
+
+При таймаутах:
+- [ ] Node Port совпадает в конфигурации панели и ноды.
+- [ ] Панель может достучаться до порта ноды (telnet/curl).
+- [ ] Контейнер ноды запущен.
+- [ ] Сетевое подключение стабильное.
+- [ ] Нет блокировок файрвола между панелью и нодой.
+
+При проблемах с Telegram OAuth:
+- [ ] Домен правильно настроен в BotFather.
+- [ ] Используется поддерживаемая доменная зона (не `.xyz`).
+- [ ] Настройки сохранены в панели.
+
+---
+
+## Дополнительные ресурсы
+
+- Руководство по установке: https://remna.st/docs/overview/quick-start/
+- Инструкция по использованию панели: https://remna.st/blog/learn
+- Установка панели: https://remna.st/docs/install/remnawave-panel/
+- Установка ноды: https://remna.st/docs/install/remnawave-node/
+- Настройка страницы подписки: https://remna.st/docs/install/subscription-page/bundled/
+- Переменные окружения: https://remna.st/docs/install/environment-variables/
+- Руководство по обновлению: https://remna.st/docs/install/upgrading/
+- Документация API: https://remna.st/api/
+- Telegram-канал: https://t.me/s/remnawave
+- GitHub Issues: https://github.com/remnawave/panel/issues

From 3aef5cd90b6a95702702fa6309762da7baba3998 Mon Sep 17 00:00:00 2001
From: Liremant <mail.liremant@gmail.com>
Date: Thu, 30 Oct 2025 14:49:43 +0800
Subject: [PATCH 2/5] docs(common-issues): add checks for nodes status
 CONNECTED but not working

---
 docs/common-issues.md | 49 +++++++++++++++++++++++++++----------------
 1 file changed, 31 insertions(+), 18 deletions(-)

diff --git a/docs/common-issues.md b/docs/common-issues.md
index 05362788..8ce0982a 100644
--- a/docs/common-issues.md
+++ b/docs/common-issues.md
@@ -16,17 +16,17 @@
 1. Неправильный путь URL
    - Проблема: Вы открываете корневой домен без UUID подписки.
    - Решение: Используйте формат:
-```
-https://sub.example.com/<shortUuid>
-```
+     ```
+     https://sub.example.com/<shortUuid>
+     ```
 
 2. Конфигурация реверс-прокси
    - Проблема: Прокси не перенаправляет запросы на контейнер страницы подписки.
    - Решение: Убедитесь, что прокси направляет трафик на `remnawave-subscription-page:3010`.
    - Проверка: Посмотрите логи контейнера страницы подписки:
-```bash
-docker compose logs -t -f
-```
+     ```bash
+     docker compose logs
+     ```
 
 3. Переменные окружения
    - Проверьте значение `SUB_PUBLIC_DOMAIN` в `.env` панели.
@@ -61,9 +61,9 @@ docker compose logs -t -f
 3. Конфигурация ноды
    - Проверьте соответствие переменных окружения ноды настройкам панели.
    - Просмотрите логи контейнера ноды:
-```bash
-docker compose logs -t -f
-```
+     ```bash
+     docker compose logs -f -t
+     ```
    - Убедитесь, что нода запустилась без ошибок привязки портов.
 
 ### Чеклист (короткий)
@@ -154,17 +154,17 @@ docker compose logs -t -f
 ### Решение (rescue CLI)
 
 1. Откройте контейнер панели:
-```bash
-docker exec -it remnawave remnawave
-```
+   ```bash
+   docker exec -it remnawave remnawave
+   ```
 2. В rescue CLI выполните действие:
-```
-● Fix Collation (Fix Collation issues for current database)
-```
+   ```
+   ● Fix Collation (Fix Collation issues for current database)
+   ```
 3. Перезапустите панель:
-```bash
-docker compose down && docker compose up -d
-```
+   ```bash
+   docker compose down && docker compose up -d
+   ```
 
 Примечание: такие ошибки чаще появляются при смене мажорной версии PostgreSQL, когда collations старой БД не совпадают с требуемыми новой версии.
 
@@ -222,6 +222,19 @@ METRICS_PASS=password
 - [ ] Переменные окружения установлены верно.
 - [ ] Сервисы перезапущены после изменений.
 
+Если cостояние ноды CONNECTED, но функциональность не работает:
+- [ ] Убедитесь, что ноды в статусе CONNECTED (UI + логи).
+- [ ] Проверьте корректность конфигурации ноды: servernames, target, dest и др.
+- [ ] Убедитесь, что целевые адреса/порты доступны с хоста ноды.
+- [ ] Проверьте настройки панели, специфичные для работы ноды:
+  - [ ] Пользователь назначен в Internal Squad.
+  - [ ] Internal Squad имеет включённые Inbounds (берутся из Config Profile).
+  - [ ] Внутренний сквад/хосты правильно назначены и активны.
+- [ ] Проверьте, что на хосте нет overrides в Advanced (Advanced → Overrides).
+- [ ] После изменений в Hosts или Internal Squads обновите подписки в клиентских приложениях.
+- [ ] Просмотрите логи ноды на WARN/ERROR по маршрутизации, TLS, DNS и аутентификации.
+- [ ] Проверьте локальные правила файрвола на хосте ноды.
+
 При таймаутах:
 - [ ] Node Port совпадает в конфигурации панели и ноды.
 - [ ] Панель может достучаться до порта ноды (telnet/curl).

From 6992df4bc65bd1417b8c32849bf05641a7a87f45 Mon Sep 17 00:00:00 2001
From: Liremant <mail.liremant@gmail.com>
Date: Thu, 30 Oct 2025 22:55:10 +0800
Subject: [PATCH 3/5] docs(remnanode): lines with the .env file have been
 removed and replaced with the current format (environment in docker-compose)

---
 docs/install/remnawave-node.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/install/remnawave-node.md b/docs/install/remnawave-node.md
index 0a39cc59..634b2f24 100644
--- a/docs/install/remnawave-node.md
+++ b/docs/install/remnawave-node.md
@@ -79,8 +79,9 @@ services:
         image: remnawave/node:latest
         restart: always
         network_mode: host
-        env_file:
-            - .env
+        environment:
+            - NODE_PORT=2222
+            - SECRET_KEY="" 
         // highlight-next-line-green
         volumes:
             // highlight-next-line-green
@@ -138,8 +139,9 @@ services:
         image: remnawave/node:latest
         restart: always
         network_mode: host
-        env_file:
-            - .env
+        environment:
+            - NODE_PORT=2222
+            - SECRET_KEY="" # Paste your SECRET_KEY here
         // highlight-next-line-green
         volumes:
             // highlight-next-line-green

From eef3096484bd0322103c68654c78d33605a5f74a Mon Sep 17 00:00:00 2001
From: Liremant <mail.liremant@gmail.com>
Date: Sun, 2 Nov 2025 02:30:55 +0800
Subject: [PATCH 4/5] docs(troubleshooting): english version of the file added

---
 docs/common-issues-EN.md | 263 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 263 insertions(+)
 create mode 100644 docs/common-issues-EN.md

diff --git a/docs/common-issues-EN.md b/docs/common-issues-EN.md
new file mode 100644
index 00000000..1b67f82b
--- /dev/null
+++ b/docs/common-issues-EN.md
@@ -0,0 +1,263 @@
+# Troubleshooting
+
+This section contains frequently encountered issues when operating the Remnawave panel, their symptoms, and step-by-step instructions for diagnosis and resolution. For each problem, symptoms, probable causes, and practical checks are provided.
+
+---
+
+## 502 Bad Gateway on Subscription Page
+
+### Symptoms
+
+- When navigating to the subscription page domain, a 502 Bad Gateway error is returned.
+- Subscription page links don't work or return a server error.
+
+### Common Causes and Solutions
+
+1. Incorrect URL Path
+   - Problem: You're opening the root domain without the subscription UUID.
+   - Solution: Use the format:
+     ```
+     https://sub.example.com/<shortUuid>
+     ```
+
+2. Reverse Proxy Configuration
+   - Problem: Proxy doesn't forward requests to the subscription page container.
+   - Solution: Ensure the proxy directs traffic to `remnawave-subscription-page:3010`.
+   - Check: View subscription page container logs:
+     ```bash
+     docker compose logs
+     ```
+
+3. Environment Variables
+   - Check the `SUB_PUBLIC_DOMAIN` value in the panel's `.env` file.
+   - Restart the panel container after changes.
+
+4. General 502 Checks
+   - Ensure DNS points to the correct IP.
+   - Verify subscription container/backend availability.
+   - Check timeouts in reverse proxy configuration.
+   - Check firewall/WAF rules.
+
+---
+
+## "timeout of 45000ms exceeded" in Panel
+
+### Symptoms
+
+- A timeout error message appears in the panel interface during node operations (e.g., getting status or management).
+
+### Common Causes and Solutions
+
+1. Incorrect Node Port Configuration
+   - Problem: Panel cannot connect to the node's REST API on the specified port.
+   - Solution: Ensure the `Node Port` value on the node matches the port used when generating docker-compose for the panel.
+   - Check: From the panel host, verify node port accessibility (telnet/curl).
+
+2. Network Issues
+   - Problem: Blocking/high latency between panel and node.
+   - Solution: Ensure stable network connection; if possible, place the node on a server with a reliable channel.
+   - Option: For complex topologies, consider Cloudflare Tunnel.
+
+3. Node Configuration
+   - Verify node environment variables match panel settings.
+   - Review node container logs:
+     ```bash
+     docker compose logs -f -t
+     ```
+   - Ensure the node started without port binding errors.
+
+### Quick Checklist
+
+- [ ] Active squad selected in user profile.
+- [ ] Internal squad has assigned inbounds.
+- [ ] At least one host exists and is enabled.
+- [ ] Host is linked to an inbound assigned to the squad.
+
+---
+
+## 502 After Panel Update
+
+### Symptoms
+
+- After updating the panel, some requests return 502.
+
+### Solutions
+
+1. Restart Services
+   - Follow the Upgrading section in the documentation.
+   - Restart panel and dependent services.
+   - Ensure containers use updated images.
+
+2. Reverse Proxy
+   - If proxy runs separately, restart it.
+   - Verify its configuration still points to correct containers/networks.
+
+---
+
+## Telegram OAuth: "domain invalid"
+
+### Symptoms
+
+- "domain invalid" error appears when attempting Telegram authorization.
+- OAuth fails validation.
+
+### Solution
+
+1. Domain Setup in BotFather
+   - Open @BotFather → Bot Settings → Domain.
+   - Specify the panel domain, for example:
+     ```
+     https://panel.domain.com
+     ```
+   - Save settings in panel: Settings → Telegram.
+
+2. Telegram Limitations
+   - Important: Telegram OAuth doesn't support `.xyz` domains. Use `.com`, `.net`, `.org`, etc.
+   - Incorrect domain will cause OAuth verification failure.
+
+---
+
+## ECONNREFUSED After Node Reinstallation
+
+### Symptoms
+
+- Panel cannot connect to node; ECONNREFUSED in logs.
+
+### Solutions
+
+1. Check Environment Variables
+   - Ensure node parameters match those generated by the panel.
+   - Confirm correct `Node Port`.
+
+2. Restart and Check Node
+   - Restart the node:
+     ```bash
+     docker compose down && docker compose up -d
+     ```
+   - View logs:
+     ```bash
+     docker compose logs -f -t
+     ```
+   - Ensure no port binding errors and port availability.
+
+3. Panel URL Configuration
+   - Check `REMNAWAVE_PANEL_URL` for subscription page — it should point to a reachable panel domain or internal service.
+
+---
+
+## Collation Errors After PostgreSQL Update
+
+### Symptoms
+
+- After a major PostgreSQL update, database collation errors occur.
+
+### Solution (rescue CLI)
+
+1. Open panel container:
+   ```bash
+   docker exec -it remnawave remnawave
+   ```
+2. Execute action in rescue CLI:
+   ```
+   ● Fix Collation (Fix Collation issues for current database)
+   ```
+3. Restart panel:
+   ```bash
+   docker compose down && docker compose up -d
+   ```
+
+Note: Such errors commonly appear when changing PostgreSQL major versions, when old database collations don't match new version requirements.
+
+---
+
+## Key Environment Variables
+
+Panel configuration:
+
+```bash
+# Panel domain for CORS/UI
+FRONT_END_DOMAIN=panel.yourdomain.com
+
+# Public URL for subscription page
+SUB_PUBLIC_DOMAIN=sub.yourdomain.com
+# or for bundled installation:
+# SUB_PUBLIC_DOMAIN=panel.yourdomain.com/api/sub
+```
+
+Subscription page:
+
+```bash
+# Custom subscription prefix (optional)
+CUSTOM_SUB_PREFIX=/custom-path
+
+# Panel URL for API access
+REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
+```
+
+Additional options:
+
+```bash
+# Enable API documentation
+IS_DOCS_ENABLED=true
+SWAGGER_PATH=/swagger
+SCALAR_PATH=/scalar
+
+# Prometheus metrics
+METRICS_USER=admin
+METRICS_PASS=password
+```
+
+Important: Restart corresponding services after changing environment variables.
+
+---
+
+## Quick Diagnostic Checklist
+
+For 502:
+- [ ] DNS resolves to correct IP.
+- [ ] Backend container is running.
+- [ ] Reverse proxy configuration is correct.
+- [ ] Service is accessible via correct path (domain vs subpath).
+- [ ] Proxy timeouts are adequately configured.
+- [ ] Environment variables are set correctly.
+- [ ] Services restarted after changes.
+
+If node status is CONNECTED but functionality doesn't work:
+- [ ] Ensure nodes are in CONNECTED status (UI + logs).
+- [ ] Check correct node configuration: servernames, target, dest, etc.
+- [ ] Ensure target addresses/ports are accessible from node host.
+- [ ] Check panel settings specific to node operation:
+  - [ ] User assigned to Internal Squad.
+  - [ ] Internal Squad has enabled Inbounds (from Config Profile).
+  - [ ] Internal squad/hosts correctly assigned and active.
+- [ ] Check that host has no overrides in Advanced (Advanced → Overrides).
+- [ ] After changes in Hosts or Internal Squads, update subscriptions in client applications.
+- [ ] Review node logs for WARN/ERROR regarding routing, TLS, DNS, and authentication.
+- [ ] Check local firewall rules on node host.
+
+For timeouts:
+- [ ] Node Port matches in panel and node configuration.
+- [ ] Panel can reach node port (telnet/curl).
+- [ ] Node container is running.
+- [ ] Network connection is stable.
+- [ ] No firewall blocks between panel and node.
+
+For Telegram OAuth issues:
+- [ ] Domain correctly configured in BotFather.
+- [ ] Using supported domain zone (not `.xyz`).
+- [ ] Settings saved in panel.
+
+---
+
+## Additional Resources
+
+- Installation Guide: https://remna.st/docs/overview/quick-start/
+- Panel Usage Instructions: https://remna.st/blog/learn
+- Panel Installation: https://remna.st/docs/install/remnawave-panel/
+- Node Installation: https://remna.st/docs/install/remnawave-node/
+- Subscription Page Setup: https://remna.st/docs/install/subscription-page/bundled/
+- Environment Variables: https://remna.st/docs/install/environment-variables/
+- Upgrade Guide: https://remna.st/docs/install/upgrading/
+- API Documentation: https://remna.st/api/
+- Telegram Channel: https://t.me/s/remnawave
+- GitHub Issues: https://github.com/remnawave/panel/issues

From edd885c0fa3dee0b58e6c37044bceedb1eb2e967 Mon Sep 17 00:00:00 2001
From: Liremant <mail.liremant@gmail.com>
Date: Sun, 2 Nov 2025 03:14:56 +0800
Subject: [PATCH 5/5] docs(troubleshooting): instead of adding a new
 commod-issues.md file, guides/common-errors.md was modified, and a Russian
 file, common-errors-ru.md, was added.

---
 docs/common-issues-EN.md        | 263 --------------------------
 docs/common-issues.md           | 263 --------------------------
 docs/guides/common-errors-ru.md | 325 ++++++++++++++++++++++++++++++++
 docs/guides/common-errors.md    | 292 +++++++++++++++++++++++++++-
 4 files changed, 611 insertions(+), 532 deletions(-)
 delete mode 100644 docs/common-issues-EN.md
 delete mode 100644 docs/common-issues.md
 create mode 100644 docs/guides/common-errors-ru.md

diff --git a/docs/common-issues-EN.md b/docs/common-issues-EN.md
deleted file mode 100644
index 1b67f82b..00000000
--- a/docs/common-issues-EN.md
+++ /dev/null
@@ -1,263 +0,0 @@
-# Troubleshooting
-
-This section contains frequently encountered issues when operating the Remnawave panel, their symptoms, and step-by-step instructions for diagnosis and resolution. For each problem, symptoms, probable causes, and practical checks are provided.
-
----
-
-## 502 Bad Gateway on Subscription Page
-
-### Symptoms
-
-- When navigating to the subscription page domain, a 502 Bad Gateway error is returned.
-- Subscription page links don't work or return a server error.
-
-### Common Causes and Solutions
-
-1. Incorrect URL Path
-   - Problem: You're opening the root domain without the subscription UUID.
-   - Solution: Use the format:
-     ```
-     https://sub.example.com/<shortUuid>
-     ```
-
-2. Reverse Proxy Configuration
-   - Problem: Proxy doesn't forward requests to the subscription page container.
-   - Solution: Ensure the proxy directs traffic to `remnawave-subscription-page:3010`.
-   - Check: View subscription page container logs:
-     ```bash
-     docker compose logs
-     ```
-
-3. Environment Variables
-   - Check the `SUB_PUBLIC_DOMAIN` value in the panel's `.env` file.
-   - Restart the panel container after changes.
-
-4. General 502 Checks
-   - Ensure DNS points to the correct IP.
-   - Verify subscription container/backend availability.
-   - Check timeouts in reverse proxy configuration.
-   - Check firewall/WAF rules.
-
----
-
-## "timeout of 45000ms exceeded" in Panel
-
-### Symptoms
-
-- A timeout error message appears in the panel interface during node operations (e.g., getting status or management).
-
-### Common Causes and Solutions
-
-1. Incorrect Node Port Configuration
-   - Problem: Panel cannot connect to the node's REST API on the specified port.
-   - Solution: Ensure the `Node Port` value on the node matches the port used when generating docker-compose for the panel.
-   - Check: From the panel host, verify node port accessibility (telnet/curl).
-
-2. Network Issues
-   - Problem: Blocking/high latency between panel and node.
-   - Solution: Ensure stable network connection; if possible, place the node on a server with a reliable channel.
-   - Option: For complex topologies, consider Cloudflare Tunnel.
-
-3. Node Configuration
-   - Verify node environment variables match panel settings.
-   - Review node container logs:
-     ```bash
-     docker compose logs -f -t
-     ```
-   - Ensure the node started without port binding errors.
-
-### Quick Checklist
-
-- [ ] Active squad selected in user profile.
-- [ ] Internal squad has assigned inbounds.
-- [ ] At least one host exists and is enabled.
-- [ ] Host is linked to an inbound assigned to the squad.
-
----
-
-## 502 After Panel Update
-
-### Symptoms
-
-- After updating the panel, some requests return 502.
-
-### Solutions
-
-1. Restart Services
-   - Follow the Upgrading section in the documentation.
-   - Restart panel and dependent services.
-   - Ensure containers use updated images.
-
-2. Reverse Proxy
-   - If proxy runs separately, restart it.
-   - Verify its configuration still points to correct containers/networks.
-
----
-
-## Telegram OAuth: "domain invalid"
-
-### Symptoms
-
-- "domain invalid" error appears when attempting Telegram authorization.
-- OAuth fails validation.
-
-### Solution
-
-1. Domain Setup in BotFather
-   - Open @BotFather → Bot Settings → Domain.
-   - Specify the panel domain, for example:
-     ```
-     https://panel.domain.com
-     ```
-   - Save settings in panel: Settings → Telegram.
-
-2. Telegram Limitations
-   - Important: Telegram OAuth doesn't support `.xyz` domains. Use `.com`, `.net`, `.org`, etc.
-   - Incorrect domain will cause OAuth verification failure.
-
----
-
-## ECONNREFUSED After Node Reinstallation
-
-### Symptoms
-
-- Panel cannot connect to node; ECONNREFUSED in logs.
-
-### Solutions
-
-1. Check Environment Variables
-   - Ensure node parameters match those generated by the panel.
-   - Confirm correct `Node Port`.
-
-2. Restart and Check Node
-   - Restart the node:
-     ```bash
-     docker compose down && docker compose up -d
-     ```
-   - View logs:
-     ```bash
-     docker compose logs -f -t
-     ```
-   - Ensure no port binding errors and port availability.
-
-3. Panel URL Configuration
-   - Check `REMNAWAVE_PANEL_URL` for subscription page — it should point to a reachable panel domain or internal service.
-
----
-
-## Collation Errors After PostgreSQL Update
-
-### Symptoms
-
-- After a major PostgreSQL update, database collation errors occur.
-
-### Solution (rescue CLI)
-
-1. Open panel container:
-   ```bash
-   docker exec -it remnawave remnawave
-   ```
-2. Execute action in rescue CLI:
-   ```
-   ● Fix Collation (Fix Collation issues for current database)
-   ```
-3. Restart panel:
-   ```bash
-   docker compose down && docker compose up -d
-   ```
-
-Note: Such errors commonly appear when changing PostgreSQL major versions, when old database collations don't match new version requirements.
-
----
-
-## Key Environment Variables
-
-Panel configuration:
-
-```bash
-# Panel domain for CORS/UI
-FRONT_END_DOMAIN=panel.yourdomain.com
-
-# Public URL for subscription page
-SUB_PUBLIC_DOMAIN=sub.yourdomain.com
-# or for bundled installation:
-# SUB_PUBLIC_DOMAIN=panel.yourdomain.com/api/sub
-```
-
-Subscription page:
-
-```bash
-# Custom subscription prefix (optional)
-CUSTOM_SUB_PREFIX=/custom-path
-
-# Panel URL for API access
-REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
-```
-
-Additional options:
-
-```bash
-# Enable API documentation
-IS_DOCS_ENABLED=true
-SWAGGER_PATH=/swagger
-SCALAR_PATH=/scalar
-
-# Prometheus metrics
-METRICS_USER=admin
-METRICS_PASS=password
-```
-
-Important: Restart corresponding services after changing environment variables.
-
----
-
-## Quick Diagnostic Checklist
-
-For 502:
-- [ ] DNS resolves to correct IP.
-- [ ] Backend container is running.
-- [ ] Reverse proxy configuration is correct.
-- [ ] Service is accessible via correct path (domain vs subpath).
-- [ ] Proxy timeouts are adequately configured.
-- [ ] Environment variables are set correctly.
-- [ ] Services restarted after changes.
-
-If node status is CONNECTED but functionality doesn't work:
-- [ ] Ensure nodes are in CONNECTED status (UI + logs).
-- [ ] Check correct node configuration: servernames, target, dest, etc.
-- [ ] Ensure target addresses/ports are accessible from node host.
-- [ ] Check panel settings specific to node operation:
-  - [ ] User assigned to Internal Squad.
-  - [ ] Internal Squad has enabled Inbounds (from Config Profile).
-  - [ ] Internal squad/hosts correctly assigned and active.
-- [ ] Check that host has no overrides in Advanced (Advanced → Overrides).
-- [ ] After changes in Hosts or Internal Squads, update subscriptions in client applications.
-- [ ] Review node logs for WARN/ERROR regarding routing, TLS, DNS, and authentication.
-- [ ] Check local firewall rules on node host.
-
-For timeouts:
-- [ ] Node Port matches in panel and node configuration.
-- [ ] Panel can reach node port (telnet/curl).
-- [ ] Node container is running.
-- [ ] Network connection is stable.
-- [ ] No firewall blocks between panel and node.
-
-For Telegram OAuth issues:
-- [ ] Domain correctly configured in BotFather.
-- [ ] Using supported domain zone (not `.xyz`).
-- [ ] Settings saved in panel.
-
----
-
-## Additional Resources
-
-- Installation Guide: https://remna.st/docs/overview/quick-start/
-- Panel Usage Instructions: https://remna.st/blog/learn
-- Panel Installation: https://remna.st/docs/install/remnawave-panel/
-- Node Installation: https://remna.st/docs/install/remnawave-node/
-- Subscription Page Setup: https://remna.st/docs/install/subscription-page/bundled/
-- Environment Variables: https://remna.st/docs/install/environment-variables/
-- Upgrade Guide: https://remna.st/docs/install/upgrading/
-- API Documentation: https://remna.st/api/
-- Telegram Channel: https://t.me/s/remnawave
-- GitHub Issues: https://github.com/remnawave/panel/issues
diff --git a/docs/common-issues.md b/docs/common-issues.md
deleted file mode 100644
index 8ce0982a..00000000
--- a/docs/common-issues.md
+++ /dev/null
@@ -1,263 +0,0 @@
-# Устранение неполадок (Troubleshooting)
-
-В этом разделе собраны часто встречающиеся проблемы при эксплуатации панели Remnawave, признаки их проявления и пошаговые инструкции по диагностике и устранению. Для каждой проблемы указаны симптомы, вероятные причины и практические проверки.
-
----
-
-## 502 Bad Gateway на странице подписки
-
-### Симптомы
-
-- При переходе на домен страницы подписки возвращается 502 Bad Gateway.
-- Ссылки на страницу подписки не работают или возвращают ошибку сервера.
-
-### Частые причины и шаги решения
-
-1. Неправильный путь URL
-   - Проблема: Вы открываете корневой домен без UUID подписки.
-   - Решение: Используйте формат:
-     ```
-     https://sub.example.com/<shortUuid>
-     ```
-
-2. Конфигурация реверс-прокси
-   - Проблема: Прокси не перенаправляет запросы на контейнер страницы подписки.
-   - Решение: Убедитесь, что прокси направляет трафик на `remnawave-subscription-page:3010`.
-   - Проверка: Посмотрите логи контейнера страницы подписки:
-     ```bash
-     docker compose logs
-     ```
-
-3. Переменные окружения
-   - Проверьте значение `SUB_PUBLIC_DOMAIN` в `.env` панели.
-   - После правки перезапустите контейнер панели.
-
-4. Общие проверки при 502
-   - Убедитесь, что DNS указывает на правильный IP.
-   - Проверьте доступность контейнера/бэкенда подписки.
-   - Проверьте таймауты в конфигурации реверс-прокси.
-   - Проверьте правила файрвола/WAF.
-
----
-
-## "timeout of 45000ms exceeded" в панели
-
-### Симптомы
-
-- В интерфейсе панели появляется сообщение об ошибке таймаута при операциях с нодами (например, при получении статуса или управлении).
-
-### Частые причины и шаги решения
-
-1. Неправильная конфигурация порта ноды
-   - Проблема: Панель не может подключиться к REST API ноды по указанному порту.
-   - Решение: Убедитесь, что значение `Node Port` на ноде совпадает с портом, который использовался при генерации docker-compose для панели.
-   - Проверка: С хоста панели проверьте доступность порта ноды (telnet/curl).
-
-2. Сетевые проблемы
-   - Проблема: Блокировки/высокая задержка между панелью и нодой.
-   - Решение: Обеспечьте стабильное сетевое соединение; по возможности разместите ноду на сервере с надёжным каналом.
-   - Опция: Для сложных топологий рассмотрите Cloudflare Tunnel.
-
-3. Конфигурация ноды
-   - Проверьте соответствие переменных окружения ноды настройкам панели.
-   - Просмотрите логи контейнера ноды:
-     ```bash
-     docker compose logs -f -t
-     ```
-   - Убедитесь, что нода запустилась без ошибок привязки портов.
-
-### Чеклист (короткий)
-
-- [ ] В профиле пользователя выбран активный сквад.
-- [ ] Внутреннему скваду назначены инбаунды.
-- [ ] Есть минимум один хост и он включён.
-- [ ] Хост привязан к инбаунду, выданному скваду.
-
----
-
-## 502 после обновления панели
-
-### Симптомы
-
-- После обновления панели часть запросов возвращает 502.
-
-### Решения
-
-1. Перезапуск сервисов
-   - Следуйте разделу Upgrading в документации.
-   - Перезапустите панель и зависимые сервисы.
-   - Убедитесь, что контейнеры используют обновлённые образы.
-
-2. Реверс-прокси
-   - Если прокси работает отдельно, перезапустите его.
-   - Проверьте, что его конфигурация по-прежнему указывает на правильные контейнеры/сети.
-
----
-
-## Telegram OAuth: "domain invalid"
-
-### Симптомы
-
-- При попытке авторизации через Telegram появляется "domain invalid".
-- OAuth не проходит валидацию.
-
-### Решение
-
-1. Настройка домена в BotFather
-   - Откройте @BotFather → Bot Settings → Domain.
-   - Укажите домен панели, например:
-     ```
-     https://panel.domain.com
-     ```
-   - Сохраните настройки в панели: Settings → Telegram.
-
-2. Ограничения Telegram
-   - Важно: OAuth Telegram не поддерживает домены в зоне `.xyz`. Используйте `.com`, `.net`, `.org` и т.д.
-   - Неправильный домен приведёт к сбою верификации OAuth.
-
----
-
-## ECONNREFUSED после переустановки ноды
-
-### Симптомы
-
-- Панель не может подключиться к ноде; в логах — ECONNREFUSED.
-
-### Решения
-
-1. Проверьте переменные окружения
-   - Убедитесь, что параметры ноды соответствуют тем, которые сгенерировала панель.
-   - Подтвердите корректность `Node Port`.
-
-2. Перезапуск и проверка ноды
-   - Перезапустите ноду:
-     ```bash
-     docker compose down && docker compose up -d
-     ```
-   - Просмотрите логи:
-     ```bash
-     docker compose logs -f -t
-     ```
-   - Убедитесь в отсутствии ошибок привязки портов и в доступности порта.
-
-3. Конфигурация URL панели
-   - Проверьте `REMNAWAVE_PANEL_URL` для страницы подписки — он должен указывать на достижимый домен панели или внутренний сервис.
-
----
-
-## Ошибки collation после обновления PostgreSQL
-
-### Симптомы
-
-- После мажорного обновления PostgreSQL возникают ошибки, связанные с collation базы данных.
-
-### Решение (rescue CLI)
-
-1. Откройте контейнер панели:
-   ```bash
-   docker exec -it remnawave remnawave
-   ```
-2. В rescue CLI выполните действие:
-   ```
-   ● Fix Collation (Fix Collation issues for current database)
-   ```
-3. Перезапустите панель:
-   ```bash
-   docker compose down && docker compose up -d
-   ```
-
-Примечание: такие ошибки чаще появляются при смене мажорной версии PostgreSQL, когда collations старой БД не совпадают с требуемыми новой версии.
-
----
-
-## Ключевые переменные окружения
-
-Конфигурация панели:
-
-```bash
-# Домен панели для CORS/UI
-FRONT_END_DOMAIN=panel.yourdomain.com
-
-# Публичный URL страницы подписки
-SUB_PUBLIC_DOMAIN=sub.yourdomain.com
-# или для bundled-установки:
-# SUB_PUBLIC_DOMAIN=panel.yourdomain.com/api/sub
-```
-
-Страница подписки:
-
-```bash
-# Кастомный префикс подписки (опционально)
-CUSTOM_SUB_PREFIX=/custom-path
-
-# URL панели для доступа к API
-REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
-```
-
-Дополнительные опции:
-
-```bash
-# Включить документацию API
-IS_DOCS_ENABLED=true
-SWAGGER_PATH=/swagger
-SCALAR_PATH=/scalar
-
-# Метрики Prometheus
-METRICS_USER=admin
-METRICS_PASS=password
-```
-
-Важно: После изменения переменных окружения перезапускайте соответствующие сервисы.
-
----
-
-## Быстрый диагностический чек-лист
-
-При 502:
-- [ ] DNS резолвится в правильный IP.
-- [ ] Контейнер бэкенда запущен.
-- [ ] Конфигурация реверс-прокси корректна.
-- [ ] Сервис доступен по правильному пути (домен vs подпуть).
-- [ ] Таймауты прокси настроены адекватно.
-- [ ] Переменные окружения установлены верно.
-- [ ] Сервисы перезапущены после изменений.
-
-Если cостояние ноды CONNECTED, но функциональность не работает:
-- [ ] Убедитесь, что ноды в статусе CONNECTED (UI + логи).
-- [ ] Проверьте корректность конфигурации ноды: servernames, target, dest и др.
-- [ ] Убедитесь, что целевые адреса/порты доступны с хоста ноды.
-- [ ] Проверьте настройки панели, специфичные для работы ноды:
-  - [ ] Пользователь назначен в Internal Squad.
-  - [ ] Internal Squad имеет включённые Inbounds (берутся из Config Profile).
-  - [ ] Внутренний сквад/хосты правильно назначены и активны.
-- [ ] Проверьте, что на хосте нет overrides в Advanced (Advanced → Overrides).
-- [ ] После изменений в Hosts или Internal Squads обновите подписки в клиентских приложениях.
-- [ ] Просмотрите логи ноды на WARN/ERROR по маршрутизации, TLS, DNS и аутентификации.
-- [ ] Проверьте локальные правила файрвола на хосте ноды.
-
-При таймаутах:
-- [ ] Node Port совпадает в конфигурации панели и ноды.
-- [ ] Панель может достучаться до порта ноды (telnet/curl).
-- [ ] Контейнер ноды запущен.
-- [ ] Сетевое подключение стабильное.
-- [ ] Нет блокировок файрвола между панелью и нодой.
-
-При проблемах с Telegram OAuth:
-- [ ] Домен правильно настроен в BotFather.
-- [ ] Используется поддерживаемая доменная зона (не `.xyz`).
-- [ ] Настройки сохранены в панели.
-
----
-
-## Дополнительные ресурсы
-
-- Руководство по установке: https://remna.st/docs/overview/quick-start/
-- Инструкция по использованию панели: https://remna.st/blog/learn
-- Установка панели: https://remna.st/docs/install/remnawave-panel/
-- Установка ноды: https://remna.st/docs/install/remnawave-node/
-- Настройка страницы подписки: https://remna.st/docs/install/subscription-page/bundled/
-- Переменные окружения: https://remna.st/docs/install/environment-variables/
-- Руководство по обновлению: https://remna.st/docs/install/upgrading/
-- Документация API: https://remna.st/api/
-- Telegram-канал: https://t.me/s/remnawave
-- GitHub Issues: https://github.com/remnawave/panel/issues
diff --git a/docs/guides/common-errors-ru.md b/docs/guides/common-errors-ru.md
new file mode 100644
index 00000000..26b7c084
--- /dev/null
+++ b/docs/guides/common-errors-ru.md
@@ -0,0 +1,325 @@
+---
+sidebar_position: 2
+title: Устранение неполадок
+---
+
+## Страница подписки
+
+### 502 Bad Gateway на странице подписки {#502-bad-gateway-subscription-page}
+
+#### Проблема
+
+При переходе на домен страницы подписки возвращается ошибка 502 Bad Gateway.
+
+#### Почему это происходит
+
+Данная ошибка возникает по следующим причинам:
+
+- Неправильный путь URL — открывается корневой домен без UUID подписки
+- Реверс-прокси не перенаправляет запросы на контейнер страницы подписки
+- Неверные переменные окружения
+- DNS не указывает на правильный IP
+- Контейнер страницы подписки недоступен
+- Некорректные таймауты в конфигурации реверс-прокси
+- Блокировка файрволом/WAF
+
+#### Решение
+
+1. Используйте правильный формат URL:
+
+```
+https://sub.example.com/<shortUuid>
+```
+
+2. Убедитесь, что реверс-прокси направляет трафик на `remnawave-subscription-page:3010`.
+
+3. Проверьте логи контейнера страницы подписки:
+
+```bash
+docker compose logs -t -f
+```
+
+4. Проверьте значение `SUB_PUBLIC_DOMAIN` в `.env` панели. После правки перезапустите контейнер панели.
+
+5. Убедитесь, что DNS указывает на правильный IP.
+
+6. Проверьте доступность контейнера/бэкенда подписки.
+
+7. Проверьте таймауты в конфигурации реверс-прокси.
+
+8. Проверьте правила файрвола/WAF.
+
+---
+
+## Панель Remnawave
+
+### "timeout of 45000ms exceeded" в панели {#timeout-45000ms-exceeded}
+
+#### Проблема
+
+В интерфейсе панели появляется сообщение об ошибке таймаута при операциях с нодами.
+
+#### Почему это происходит
+
+Данная ошибка возникает по следующим причинам:
+
+- Панель не может подключиться к REST API ноды по указанному порту
+- Блокировки или высокая задержка между панелью и нодой
+- Несоответствие переменных окружения ноды настройкам панели
+
+#### Решение
+
+1. Убедитесь, что значение `Node Port` на ноде совпадает с портом, который использовался при генерации docker-compose для панели.
+
+2. С хоста панели проверьте доступность порта ноды (telnet/curl).
+
+3. Обеспечьте стабильное сетевое соединение. По возможности разместите ноду на сервере с надёжным каналом.
+
+4. Для сложных топологий рассмотрите тунеллирование между панелью и нодой (например, с помощью Tailscale).
+
+5. Проверьте соответствие переменных окружения ноды настройкам панели.
+
+6. Просмотрите логи контейнера ноды:
+
+```bash
+docker compose logs -f -t
+```
+
+7. Убедитесь, что нода запустилась без ошибок привязки портов.
+
+### 502 после обновления панели {#502-after-panel-upgrade}
+
+#### Проблема
+
+После обновления панели часть запросов возвращает ошибку 502.
+
+#### Почему это происходит
+
+Nginx не перезагрузился и не подхватил новый адрес от панели.
+
+#### Решение
+
+1. Следуйте разделу Upgrading в документации.
+
+2. Перезапустите панель и зависимые сервисы.
+
+3. Убедитесь, что контейнеры используют обновлённые образы.
+
+4. Если реверс-прокси работает отдельно, перезапустите его.
+
+5. Проверьте, что конфигурация прокси по-прежнему указывает на правильные контейнеры/сети.
+
+### Telegram OAuth: "domain invalid" {#telegram-oauth-domain-invalid}
+
+#### Проблема
+
+При попытке авторизации через Telegram появляется ошибка "domain invalid".
+
+#### Решение
+
+1. Откройте @BotFather → Bot Settings → Domain.
+
+2. Укажите домен панели:
+
+```
+https://panel.domain.com
+```
+
+3. Сохраните настройки в панели: Settings → Telegram.
+
+:::caution
+OAuth Telegram не поддерживает домены в зоне `.xyz`.
+:::
+
+### Ошибки collation после обновления PostgreSQL {#collation-errors-after-postgresql-upgrade}
+
+#### Проблема
+
+После мажорного обновления PostgreSQL возникают ошибки, связанные с collation базы данных.
+
+#### Почему это происходит
+
+Такие ошибки чаще появляются при смене мажорной версии PostgreSQL, когда collations старой БД не совпадают с требуемыми новой версии.
+
+#### Решение
+
+1. Откройте контейнер панели:
+
+```bash
+docker exec -it remnawave remnawave
+```
+
+2. В rescue CLI выполните действие:
+
+```
+● Fix Collation (Fix Collation issues for current database)
+```
+
+3. Перезапустите панель:
+
+```bash
+docker compose down && docker compose up -d
+```
+
+---
+
+## Нода Remnawave
+
+### ECONNREFUSED после переустановки ноды {#econnrefused-after-node-reinstall}
+
+#### Проблема
+
+Панель не может подключиться к ноде. В логах отображается ошибка ECONNREFUSED.
+
+#### Решение
+
+1. Убедитесь, что параметры ноды соответствуют тем, которые сгенерировала панель.
+
+2. Подтвердите корректность `Node Port`.
+
+3. Просмотрите логи:
+
+```bash
+docker compose logs -f -t
+```
+
+4. Убедитесь в отсутствии ошибок привязки портов и в доступности порта.
+
+5. Проверьте `REMNAWAVE_PANEL_URL` для страницы подписки — он должен указывать на достижимый домен панели или внутренний сервис. Если страница подписки установлена рядом с Remnawave - следует использовать `http://remnawave-subscription-page:3010`.
+
+### XML-RPC fault: SPAWN_ERROR: xray {#xml-rpc-fault-spawn-error-xray}
+
+#### Проблема
+
+В логах ноды отображается следующая ошибка:
+
+```title="cd /opt/remnanode && docker compose logs -f -t"
+remnanode  | ERROR [HttpExceptionFilter]      Failed to get system stats - { stack: [ null ], code: 'A010', path: '/node/stats/get-system-stats' }
+remnanode  | LOG [XrayService]      Getting config checksum...
+remnanode  | LOG [XrayService]      XTLS config generated in: 1ms
+// highlight-next-line-red
+remnanode  | ERROR [XrayService]      XML-RPC fault: SPAWN_ERROR: xray - { stack: [ null ] }
+remnanode  | LOG [XrayService]      Start XTLS took: 2s 568ms
+remnanode  | ERROR [StatsService]     Failed to get system stats: /xray.app.stats.command.StatsService/GetSysStats UNAVAILABLE: No connection established. Last error: connect ECONNREFUSED 127.0.0.1:61000 (2025-05-08T14:36:08.821Z) - { stack: [ null ], isOk: false, code: 'A002' }
+```
+
+#### Почему это происходит
+
+Данная ошибка возникает, когда Xray core не запускается из-за неправильной конфигурации.
+
+#### Решение
+
+1. Проверьте логи **Xray core** для получения детальной информации:
+
+```bash
+docker exec -it remnanode tail -n +1 -f /var/log/supervisor/xray.out.log
+```
+
+или
+
+```bash
+docker exec -it remnanode tail -n +1 -f /var/log/supervisor/xray.err.log
+```
+
+2. В большинстве случаев в логах будет указана причина, по которой Xray core не запускается.
+
+3. Исправьте проблему в панели Remnawave в разделе **Xray Config**. Сохраните изменения.
+
+---
+
+## Ключевые переменные окружения
+
+Конфигурация панели:
+
+```bash
+# Домен панели для CORS/UI
+FRONT_END_DOMAIN=panel.yourdomain.com
+
+# Публичный URL страницы подписки
+SUB_PUBLIC_DOMAIN=sub.yourdomain.com
+```
+
+Страница подписки:
+
+```bash
+# Кастомный префикс подписки (опционально)
+CUSTOM_SUB_PREFIX=/custom-path
+
+# URL панели для доступа к API
+REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
+```
+
+Дополнительные опции:
+
+```bash
+# Включить документацию API
+IS_DOCS_ENABLED=true
+SWAGGER_PATH=/swagger
+SCALAR_PATH=/scalar
+
+# Метрики Prometheus
+METRICS_USER=admin
+METRICS_PASS=password
+```
+
+:::caution
+После изменения переменных окружения перезапускайте соответствующие сервисы.
+:::
+
+---
+
+## Быстрый диагностический чек-лист
+
+При 502:
+
+- [ ] DNS резолвится в правильный IP
+- [ ] Контейнер бэкенда запущен
+- [ ] Конфигурация реверс-прокси корректна
+- [ ] Сервис доступен по правильному пути (домен vs подпуть)
+- [ ] Таймауты прокси настроены адекватно
+- [ ] Переменные окружения установлены верно
+- [ ] Сервисы перезапущены после изменений
+
+Если состояние ноды CONNECTED, но функциональность не работает:
+
+- [ ] Убедитесь, что ноды в статусе CONNECTED (UI + логи)
+- [ ] Проверьте корректность конфигурации ноды: servernames, target, dest и др.
+- [ ] Убедитесь, что целевые адреса/порты доступны с хоста ноды
+- [ ] Проверьте настройки панели:
+  - [ ] Пользователь назначен в Internal Squad
+  - [ ] Internal Squad имеет включённые Inbounds (берутся из Config Profile)
+  - [ ] Внутренний сквад/хосты правильно назначены и активны
+- [ ] Проверьте, что на хосте нет overrides в Advanced (Advanced → Overrides)
+- [ ] После изменений в Hosts или Internal Squads обновите подписки в клиентских приложениях
+- [ ] Просмотрите логи ноды на WARN/ERROR по маршрутизации, TLS, DNS и аутентификации
+- [ ] Проверьте локальные правила файрвола на хосте ноды
+
+При таймаутах:
+
+- [ ] Node Port совпадает в конфигурации панели и ноды
+- [ ] Панель может достучаться до порта ноды (telnet/curl)
+- [ ] Контейнер ноды запущен
+- [ ] Сетевое подключение стабильное
+- [ ] Нет блокировок файрвола между панелью и нодой
+
+При проблемах с Telegram OAuth:
+
+- [ ] Домен правильно настроен в BotFather
+- [ ] Используется поддерживаемая доменная зона (не `.xyz`)
+- [ ] Настройки сохранены в панели
+
+---
+
+## Дополнительные ресурсы
+
+- Руководство по установке: [https://remna.st/docs/overview/quick-start/](https://remna.st/docs/overview/quick-start/)
+- Инструкция по использованию панели: [https://remna.st/blog/learn](https://remna.st/blog/learn)
+- Установка панели: [https://remna.st/docs/install/remnawave-panel/](https://remna.st/docs/install/remnawave-panel/)
+- Установка ноды: [https://remna.st/docs/install/remnawave-node/](https://remna.st/docs/install/remnawave-node/)
+- Настройка страницы подписки: [https://remna.st/docs/install/subscription-page/bundled/](https://remna.st/docs/install/subscription-page/bundled/)
+- Переменные окружения: [https://remna.st/docs/install/environment-variables/](https://remna.st/docs/install/environment-variables/)
+- Руководство по обновлению: [https://remna.st/docs/install/upgrading/](https://remna.st/docs/install/upgrading/)
+- Документация API: [https://remna.st/api/](https://remna.st/api/)
+- Telegram-канал: [https://t.me/s/remnawave](https://t.me/s/remnawave)
+- GitHub Issues: [https://github.com/remnawave/panel/issues](https://github.com/remnawave/panel/issues)
+
diff --git a/docs/guides/common-errors.md b/docs/guides/common-errors.md
index 301b9fd6..d31503dd 100644
--- a/docs/guides/common-errors.md
+++ b/docs/guides/common-errors.md
@@ -1,15 +1,197 @@
 ---
 sidebar_position: 2
-title: Common errors
+title: Troubleshooting
+---
+
+## Subscription Page
+
+### 502 Bad Gateway on subscription page {#502-bad-gateway-subscription-page}
+
+#### Problem
+
+When navigating to the subscription page domain, a 502 Bad Gateway error is returned.
+
+#### Why this happens
+
+This error occurs for the following reasons:
+
+- Incorrect URL path — the root domain is opened without the subscription UUID
+- Reverse proxy is not forwarding requests to the subscription page container
+- Invalid environment variables
+- DNS is not pointing to the correct IP
+- Subscription page container is unavailable
+- Incorrect timeouts in reverse proxy configuration
+- Firewall/WAF blocking
+
+#### Solution
+
+1. Use the correct URL format:
+
+```
+https://sub.example.com/<shortUuid>
+```
+
+2. Ensure that the reverse proxy forwards traffic to `remnawave-subscription-page:3010`.
+
+3. Check the subscription page container logs:
+
+```bash
+docker compose logs -t -f
+```
+
+4. Verify the `SUB_PUBLIC_DOMAIN` value in the panel's `.env` file. After editing, restart the panel container.
+
+5. Ensure that DNS points to the correct IP.
+
+6. Check the availability of the subscription container/backend.
+
+7. Verify timeouts in the reverse proxy configuration.
+
+8. Check firewall/WAF rules.
+
+---
+
+## Remnawave Panel
+
+### "timeout of 45000ms exceeded" in panel {#timeout-45000ms-exceeded}
+
+#### Problem
+
+A timeout error message appears in the panel interface during node operations.
+
+#### Why this happens
+
+This error occurs for the following reasons:
+
+- Panel cannot connect to the node's REST API on the specified port
+- Blocking or high latency between panel and node
+- Node environment variables do not match panel settings
+
+#### Solution
+
+1. Ensure that the `Node Port` value on the node matches the port used when generating docker-compose for the panel.
+
+2. From the panel host, check the availability of the node port (telnet/curl).
+
+3. Ensure stable network connectivity. If possible, place the node on a server with a reliable connection.
+
+4. For complex topologies, consider tunneling between the panel and node (e.g., using Tailscale).
+
+5. Verify that the node's environment variables match the panel settings.
+
+6. Review the node container logs:
+
+```bash
+docker compose logs -f -t
+```
+
+7. Ensure the node started without port binding errors.
+
+### 502 after panel upgrade {#502-after-panel-upgrade}
+
+#### Problem
+
+After upgrading the panel, some requests return a 502 error.
+
+#### Why this happens
+
+Nginx has not reloaded and has not picked up the new address from the panel.
+
+#### Solution
+
+1. Follow the Upgrading section in the documentation.
+
+2. Restart the panel and dependent services.
+
+3. Ensure containers are using updated images.
+
+4. If the reverse proxy runs separately, restart it.
+
+5. Verify that the proxy configuration still points to the correct containers/networks.
+
+### Telegram OAuth: "domain invalid" {#telegram-oauth-domain-invalid}
+
+#### Problem
+
+When attempting to authenticate via Telegram, a "domain invalid" error appears.
+
+#### Solution
+
+1. Open @BotFather → Bot Settings → Domain.
+
+2. Specify the panel domain:
+
+```
+https://panel.domain.com
+```
+
+3. Save settings in the panel: Settings → Telegram.
+
+:::caution
+Telegram OAuth does not support domains in the `.xyz` TLD.
+:::
+
+### Collation errors after PostgreSQL upgrade {#collation-errors-after-postgresql-upgrade}
+
+#### Problem
+
+After a major PostgreSQL upgrade, errors related to database collation occur.
+
+#### Why this happens
+
+Such errors most often appear when changing PostgreSQL major versions, when the old database's collations do not match those required by the new version.
+
+#### Solution
+
+1. Open the panel container:
+
+```bash
+docker exec -it remnawave remnawave
+```
+
+2. In the rescue CLI, execute the action:
+
+```
+● Fix Collation (Fix Collation issues for current database)
+```
+
+3. Restart the panel:
+
+```bash
+docker compose down && docker compose up -d
+```
+
 ---
 
 ## Remnawave Node
 
+### ECONNREFUSED after node reinstall {#econnrefused-after-node-reinstall}
+
+#### Problem
+
+The panel cannot connect to the node. ECONNREFUSED error appears in logs.
+
+#### Solution
+
+1. Ensure that the node parameters match those generated by the panel.
+
+2. Confirm the correctness of `Node Port`.
+
+3. Review the logs:
+
+```bash
+docker compose logs -f -t
+```
+
+4. Ensure there are no port binding errors and that the port is accessible.
+
+5. Check `REMNAWAVE_PANEL_URL` for the subscription page — it should point to a reachable panel domain or internal service. If the subscription page is installed alongside Remnawave, use `http://remnawave-subscription-page:3010`.
+
 ### XML-RPC fault: SPAWN_ERROR: xray {#xml-rpc-fault-spawn-error-xray}
 
 #### Problem
 
-If you see the following error:
+The following error appears in the node logs:
 
 ```title="cd /opt/remnanode && docker compose logs -f -t"
 remnanode  | ERROR [HttpExceptionFilter]      Failed to get system stats - { stack: [ null ], code: 'A010', path: '/node/stats/get-system-stats' }
@@ -23,11 +205,11 @@ remnanode  | ERROR [StatsService]     Failed to get system stats: /xray.app.stat
 
 #### Why this happens
 
-This errors occurs when Xray core failed to start, most likely due to the wrong configuration.
+This error occurs when Xray core fails to start due to incorrect configuration.
 
 #### Solution
 
-1. Check the **Xray core** logs for more details.
+1. Check the **Xray core** logs for detailed information:
 
 ```bash
 docker exec -it remnanode tail -n +1 -f /var/log/supervisor/xray.out.log
@@ -39,6 +221,104 @@ or
 docker exec -it remnanode tail -n +1 -f /var/log/supervisor/xray.err.log
 ```
 
-2. In most cases, you will see the reason why Xray core fails to start.
+2. In most cases, the logs will indicate the reason why Xray core is not starting.
+
+3. Fix the issue in the Remnawave panel in the **Xray Config** section. Save the changes.
+
+---
+
+## Key Environment Variables
+
+Panel configuration:
+
+```bash
+# Panel domain for CORS/UI
+FRONT_END_DOMAIN=panel.yourdomain.com
+
+# Public URL of subscription page
+SUB_PUBLIC_DOMAIN=sub.yourdomain.com
+```
+
+Subscription page:
+
+```bash
+# Custom subscription prefix (optional)
+CUSTOM_SUB_PREFIX=/custom-path
+
+# Panel URL for API access
+REMNAWAVE_PANEL_URL=https://panel.yourdomain.com
+```
+
+Additional options:
+
+```bash
+# Enable API documentation
+IS_DOCS_ENABLED=true
+SWAGGER_PATH=/swagger
+SCALAR_PATH=/scalar
+
+# Prometheus metrics
+METRICS_USER=admin
+METRICS_PASS=password
+```
+
+:::caution
+After changing environment variables, restart the corresponding services.
+:::
+
+---
+
+## Quick Diagnostic Checklist
+
+For 502 errors:
+
+- [ ] DNS resolves to the correct IP
+- [ ] Backend container is running
+- [ ] Reverse proxy configuration is correct
+- [ ] Service is accessible via the correct path (domain vs subpath)
+- [ ] Proxy timeouts are configured adequately
+- [ ] Environment variables are set correctly
+- [ ] Services have been restarted after changes
+
+If node status is CONNECTED but functionality doesn't work:
+
+- [ ] Ensure nodes are in CONNECTED status (UI + logs)
+- [ ] Verify node configuration correctness: servernames, target, dest, etc.
+- [ ] Ensure target addresses/ports are accessible from the node host
+- [ ] Check panel settings:
+  - [ ] User is assigned to Internal Squad
+  - [ ] Internal Squad has enabled Inbounds (taken from Config Profile)
+  - [ ] Internal squad/hosts are properly assigned and active
+- [ ] Check that there are no overrides on the host in Advanced (Advanced → Overrides)
+- [ ] After changes in Hosts or Internal Squads, update subscriptions in client applications
+- [ ] Review node logs for WARN/ERROR regarding routing, TLS, DNS, and authentication
+- [ ] Check local firewall rules on the node host
+
+For timeouts:
+
+- [ ] Node Port matches in both panel and node configuration
+- [ ] Panel can reach the node port (telnet/curl)
+- [ ] Node container is running
+- [ ] Network connection is stable
+- [ ] No firewall blocking between panel and node
+
+For Telegram OAuth issues:
+
+- [ ] Domain is correctly configured in BotFather
+- [ ] Using a supported domain zone (not `.xyz`)
+- [ ] Settings are saved in the panel
+
+---
+
+## Additional Resources
 
-3. Fix the issue in Remnawave Panel dashboard under **Xray Config** section. Save the changes.
+- Installation guide: [https://remna.st/docs/overview/quick-start/](https://remna.st/docs/overview/quick-start/)
+- Panel usage instructions: [https://remna.st/blog/learn](https://remna.st/blog/learn)
+- Panel installation: [https://remna.st/docs/install/remnawave-panel/](https://remna.st/docs/install/remnawave-panel/)
+- Node installation: [https://remna.st/docs/install/remnawave-node/](https://remna.st/docs/install/remnawave-node/)
+- Subscription page setup: [https://remna.st/docs/install/subscription-page/bundled/](https://remna.st/docs/install/subscription-page/bundled/)
+- Environment variables: [https://remna.st/docs/install/environment-variables/](https://remna.st/docs/install/environment-variables/)
+- Upgrade guide: [https://remna.st/docs/install/upgrading/](https://remna.st/docs/install/upgrading/)
+- API documentation: [https://remna.st/api/](https://remna.st/api/)
+- Telegram channel: [https://t.me/s/remnawave](https://t.me/s/remnawave)
+- GitHub Issues: [https://github.com/remnawave/panel/issues](https://github.com/remnawave/panel/issues)