РОЗДІЛ 17

Усунення несправностей

Знайдіть симптом, прочитайте причину, застосуйте виправлення. Коли не певні, журнал збірки та журнал застосунку скажуть більше за будь-які здогадки.

Два місця, куди дивитися насамперед

Вкладка «Розгортання» → «Журнал збірки» — для всього, що відбувається до запуску застосунку, і вкладка «Застосунок» → «Стежити за журналом» — для всього, що після. Перші рядки журналу збірки вказують, яке середовище виконання, яку версію і який базовий образ обрала платформа.

Розгортання#

Симптом	Причина	Виправлення
`cannot autodetect runtime`	жодного з `package.json`, `requirements.txt`/`pyproject.toml`, `composer.json`/`public/index.php`, `index.html` немає в корені	запакуйте вміст теки, а не саму теку; або задайте `runtime:` у `platform.yaml`
`platform.yaml is invalid` з назвою ключа	невідомий або написаний із помилкою ключ (маніфест суворий)	виправте або видаліть ключ
`version: must be a quoted string … 3.1`	YAML прочитав `3.10` як число	напишіть `version: "3.10"`
`cannot pull base image … is that version published?`	такого релізу не існує	виберіть наявну мажорну/мінорну версію або приберіть `version`
Збірка попереджає `could not refresh …; building from the local copy`	реєстр був недоступний; використано старіший локальний образ	одноразово нешкідливо; якщо повторюється, перевірте доступ платформи до Інтернету
`node runtime: no start command`	немає скрипта `start`, немає `server.js`/`index.js`	додайте скрипт `start` або `start_cmd`
`python runtime: set 'start_cmd'…`	немає `main.py` або `app/main.py`	додайте `start_cmd: uvicorn …:app --host 0.0.0.0 --port $PORT`
`npm run build` завершується помилкою command not found (tsc, vite)	`NODE_ENV=production` змусив npm пропустити devDependencies	`install_cmd: npm ci --include=dev`
`php docroot 'public' does not exist`	неправильний `docroot`	задайте в `docroot:` справжній вебкорінь
`archive too large (> 512 MiB)`	завеликий розмір завантаження або розпакованого вмісту	приберіть `node_modules`, результати збірки й медіафайли
Розгортання зависло, потім `failed … interrupted by management restart`	платформу перезапустили посеред збірки	розгорніть знову

Застосунок працює, а сайт — ні#

Симптом	Причина	Виправлення
Сайт повертає помилку одразу після розгортання зі статусом працює	застосунок не слухає `0.0.0.0:$PORT` (наприклад, прив'язаний до `127.0.0.1` або до фіксованого порту)	читайте `PORT` зі змінних середовища й слухайте на всіх інтерфейсах
На вкладці «Застосунок» статус зупинено	його зупинили ви, або команда запуску одразу завершується	натисніть Запустити; якщо він знову завершиться, прочитайте журнал
На вкладці «Застосунок» статус відсутній	контейнера не існує (невдале перестворення або застосунок ніколи не розгортали)	розгорніть знову або натисніть Перестворити
Зміна змінної не діє	змінні застосовуються після перестворення або розгортання	натисніть Перестворити застосунок зараз
`DB_MAIN_HOST` порожня або відсутня	бази даних не існувало, коли застосунок розгортали	створіть базу даних, потім Перестворити (і перевірте назву в `databases:`)
Файли, записані застосунком, зникають	їх записано поза томом	оголосіть шлях у `volumes:` або використовуйте S3 чи базу даних
Збірка проходить, але `process.env.X` під час збірки порожня	змінні доступні лише під час роботи	значення для збірки вкажіть у `build_cmd`/`install_cmd` у `platform.yaml` або читайте їх під час запуску

Домени та сертифікати#

Симптом	Причина	Виправлення
перевірка: «помилка DNS» (`dns_failed`)	немає `A`-запису, неправильна адреса або DNS ще не поширився	виправте запис; `dig +short <name>`; натисніть Повторити перевірку
перевірка: «помилка маршрутизації» (`routing_failed`)	DNS розв'язується, але запит не доходить до платформи	ingress має пересилати 80 і 443 на `10.10.10.10`; перевірте `curl -i http://<name>/.well-known/platform/precheck`
сертифікат лишається в стані «очікує» (`pending`) або «помилка» (`error`) у prod	порт 80 заблоковано, ліміт запитів CA, неправильна контактна пошта	відкрийте порт 80; для репетиції використовуйте staging Let's Encrypt; вкажіть справжню пошту (не `admin@platform.example`)
Браузер попереджає, що з'єднання не захищене	платформа працює в режимі TLS dev	імпортуйте локальний CA або попросіть адміністратора переключити на prod
Додавання власного домену відповідає `409`	ім'я хоста належить рівно одному проєкту в межах усієї платформи, незалежно від того, як його записано	видаліть його з проєкту, який його має, або виберіть інше ім'я

Бази даних#

Симптом	Причина	Виправлення
Пароль втрачено	його показано один раз, і він зберігається зашифрованим	застосунок і далі отримує його як `DB_*`; щоб отримати нові облікові дані, створіть нову базу даних і перенесіть дані
Результат SQL обрізано	ліміт 1 000 рядків / 1 МіБ	додайте `LIMIT`, виберіть менше стовпців або створіть дамп
Запит зупинено через 30 с	тайм-аут на один оператор	оптимізуйте запит або виконайте його зі свого застосунку
Виконується лише один оператор	консоль виконує один оператор	надсилайте оператори по одному
База даних Postgres 16 не стає 17	каталог даних версії 16 не може запуститися під 17	створіть нову базу даних і зробіть дамп/відновлення в неї

Завантаження, токени та MCP#

Симптом	Причина	Виправлення
`HTTP 413 Request body too large` від MCP	`upload_archive` передає файл як base64; ліміт — 4 МіБ (≈ 3 МіБ архіву)	використайте `create_upload_url` і відправте файл через `curl -T`
Посилання для завантаження відповідає `404`	посилання невідоме, строк його дії сплив (15 хв) або воно вже використане	запросіть нове через `create_upload_url`
Посилання для завантаження відповідає `413 archive exceeds 512 MiB`	перевищено ліміт	зменште архів
`/mcp` перенаправляє на `http://` або втрачає токен	бракує кінцевої косої риски	використовуйте `/mcp/`
`authentication required` / `invalid, revoked or disabled token`	токена немає, він неправильний або відкликаний	створіть новий токен на сторінці «Токени»
`tool requires the admin role`	інструмент лише для адміністраторів викликав звичайний користувач	використайте токен адміністратора або попросіть адміністратора
`project … belongs to another user`	неправильний ідентифікатор або slug проєкту	`list_projects`
Українська консоль показує англійську помилку на кшталт «Помилка: Incorrect email or password»	серверні повідомлення не перекладаються — консоль перекладає власні тексти й передає текст сервера без змін	це очікувано; англійський опис — справжнє повідомлення
Через деякий час консоль вас розлогінює	JWT діє 8 годин	увійдіть знову; для тривалих завдань використовуйте API-токен

Для адміністраторів#

Симптом	Причина	Виправлення
У розділі «Платформа» блок «Стан» показує погіршено	якийсь компонент не працює	відкрийте рядок зі збоєм; виконайте на хості `make check` і `make logs`
Видалення користувача відповідає `409 user has N project(s)`	користувачів із проєктами видаляти не можна	спершу видаліть або передайте проєкти
Короткі розриви з'єднань після збереження налаштувань ACME	застосування перестворює Traefik	це очікувано; зачекайте кілька секунд
Після зміни CA усі сертифікати випускаються повторно	кожен CA має власне сховище сертифікатів	це очікувано; плануйте це поза піковим навантаженням
`make up` завершується помилкою вихідного доступу (egress)	хост не пересилає й не маскарадить `hosting`	виправте пересилання на хості або свідомо задайте `SKIP_EGRESS_CHECK=1`
Великі `PUT`-завантаження не проходять через ingress	ліміт розміру тіла, буферизація або тайм-аути	див. Експлуатація

Усе ще не виходить? Поширені запитання відповідають на питання, які ставлять найчастіше, а журнал аудиту показує, що саме було зроблено і ким.