🇬🇧 English | 🇺🇦 Українська
7. Помилки та діагностика¶
Три рівні відповіді¶
Кожен результат несе три речі, і читати їх варто саме в такому порядку.
| Що | Для чого | Приклад |
|---|---|---|
| Result Code | Розгалуження в коді | PermissionDenied |
| Error Code | Логи й точні перевірки | AccessDenied |
| Diagnostic Hint | Що змінити | «Ключі дійсні, але політика не дозволяє цю дію…» |
Провайдери відповідають кодами на кшталт SignatureDoesNotMatch — точними, але такими, що
нічого не кажуть про причину. А причина майже завжди — помилка в налаштуваннях, не пов'язана
з формулюванням. Підказка перекладає одне в інше.
On Failure
└─► Print String (Get S3 Diagnostic Hint)
Або одним рядком у лог: Get S3 Result Summary.
Result Code¶
| Значення | Що сталося | Куди дивитися |
|---|---|---|
Success |
Усе вдалося | — |
Partial Success |
Пакетна операція пройшла, окремі елементи — ні | Error Count, масив Results |
Network Error |
Запит не дійшов: DNS, маршрут, відмова у з'єднанні, TLS | Адреса, схема, мережа |
Timeout |
Відповідь не прийшла вчасно | Timeout Seconds, канал |
Authentication Error |
Ключі відхилено | Секрет, регіон, годинник системи |
Permission Denied |
Ключі дійсні, але дія не дозволена | Політика IAM або політика бакета |
Not Found |
Немає такого бакета чи об'єкта | Назва, регістр |
Already Exists |
Ім'я бакета зайняте | Інше ім'я |
Precondition Failed |
Об'єкт змінився під час передавання | Зчитати заново — 5. Передавання файлів |
Invalid Request |
Запит відхилено як некоректний | Майже завжди помилка в коді |
Throttled |
Провайдер обмежує швидкість | Max Retries, кількість одночасних операцій |
Server Error |
Збій на боці провайдера | Сторінка статусу провайдера |
Cancelled |
Скасовано викликом | — |
Зверніть увагу на різницю між Authentication Error і Permission Denied. Обидва приходять як
HTTP 403, але виправляються по-різному: перше — це ключ, друге — політика. Плагін розрізняє
їх за кодом помилки провайдера.
Precondition Failed (HTTP 412) — не збій зв'язку і не помилка налаштування: об'єкт у сховищі
переписали, поки його зчитували. Плагін відмовляється склеювати дві версії в один файл і
повідомляє про це замість того, щоб віддати пошкоджений результат.
Типові помилки і що з ними робити¶
SignatureDoesNotMatch¶
Найчастіша помилка першого дня.
Якщо провайдер не Amazon, а Path Style Addressing вимкнено — річ майже напевно в цьому. Оберіть провайдера у налаштуваннях зі списку, і стиль адресації проставиться правильно.
Якщо адресація вже правильна, перевіряйте в такому порядку:
- Секретний ключ — випадковий пробіл на початку чи в кінці при копіюванні.
- Регіон — він бере участь у підписі й має збігатися з регіоном бакета.
- Годинник системи — підпис дійсний у вікні ±15 хвилин.
Сам ідентифікатор ключа при цій помилці точно правильний: провайдер його впізнав, інакше відповів би інакше.
RequestTimeTooSkewed¶
Годинник машини розходиться з сервером більше ніж на 15 хвилин. Увімкніть синхронізацію часу.
InvalidAccessKeyId¶
Провайдер не знає такого ключа. Якщо ви користуєтеся тимчасовими ключами — переконайтеся, що передаєте ще й session token: без нього ключ виглядає недійсним, навіть коли ключ і секрет правильні.
AccessDenied¶
Ключі дійсні, але політика не дозволяє саме цю дію. Це не проблема ключів — правте політику IAM або політику бакета.
NoSuchBucket¶
Немає такого бакета в цьому регіоні й у цього облікового запису.
На MinIO це часто означає інше: MinIO не створює бакети на першу вимогу. Створіть його нодою S3 Create Bucket або через консоль MinIO.
PermanentRedirect / HTTP 301¶
Бакет лежить в іншому регіоні. Виправте поле Region — і на Amazon S3 адреса підлаштується сама.
NoSuchKey¶
Немає такого об'єкта. Ключі чутливі до регістру й не починаються зі слеша:
saves/player.sav, а не /saves/player.sav.
EntityTooSmall¶
Частина багаточастинного завантаження менша за 5 МБ — мінімум, який вимагає S3 для всіх
частин, крім останньої. Підніміть Multipart Part Size Bytes до 5242880 або більше.
Зазвичай сюди не потрапляють: плагін сам піднімає значення до мінімуму.
403 на List Buckets¶
Перелік бакетів потребує права рівня облікового запису, якого у ключів «на один бакет» немає. Cloudflare R2 не реалізує цю операцію взагалі й завжди відповідає відмовою — усі інші операції там працюють.
Якщо ви й так знаєте потрібний бакет, ця операція вам не потрібна.
Логи¶
Плагін пише в категорію LogDemoS3.
Log LogDemoS3 Verbose // по рядку на запит: метод, адреса
Log LogDemoS3 VeryVerbose // ще й усі підписані заголовки
Або в DefaultEngine.ini:
[Core.Log]
LogDemoS3=Verbose
VeryVerbose друкує заголовок Authorization разом зі скоупом облікових даних — увімкніть
його, коли розбираєтеся саме з підписом, і вимкніть після.
Секретний ключ у логи не потрапляє ніколи. Опис облікових даних, який ви побачите, має
вигляд AKIA... (temporary) — достатньо, щоб відрізнити один профіль від іншого, і нічого
більше.
Кнопки перевірки¶
Найшвидший спосіб зрозуміти, чи робоча конфігурація — Project Settings → Plugins → S3 Compatible Storage:
| Кнопка | Що перевіряє |
|---|---|
| Test Connection | Адреса, стиль адресації, підпис, доступ до бакета |
| List Objects | Що бакет читається, і що в ньому лежить |
| Run Round Trip Check | Повний цикл: запис, зчитування, звірка байтів, видалення |
Вони працюють тим самим кодом, що й зібрана гра, тож зелений результат означає робочу конфігурацію, а не просто синтаксично правильну. Звіт з'являється тут же, разом із підказками до помилок.
Коли нічого не допомагає¶
- Увімкніть
Log LogDemoS3 VeryVerboseі зробіть один запит. - Порівняйте адресу в лозі з тією, яку очікуєте: чи правильний хост, чи там бакет, де треба, чи закодовані спецсимволи в ключі.
- Візьміть
Request Idіз результату — провайдери шукають за ним у своїх логах, і в зверненні до підтримки він найкорисніший.
Далі: 8. Провайдери