Snapshot failure — це ситуація, коли валідатор Solana не може завантажити, розпакувати чи застосувати знімок стану (snapshot) під час старту або після перезавантаження. Без коректного snapshot вузол змушений синхронізуватися з genesis, що на mainnet-beta займає доби або взагалі нереалістично. Нижче — покрокова діагностика, орієнтована на операторів, які працюють з Agave (колишній agave-validator) на production-кластерах.

Операційні вимоги для «Як діагностувати snapshot failures» перевірено 2 серпня 2026 року. Для production використовуйте тільки реліз Agave, рекомендований для конкретного кластера, і звіряйте параметри з agave-validator --help . Офіційні вимоги Anza на цю дату орієнтують операторів на Ubuntu 24.04, щонайменше 12 ядер/24 потоки, 256 ГБ RAM, окремі швидкі NVMe та симетричний канал від 2 Гбіт/с; це рекомендації, а не гарантія достатньої продуктивності.

Ознаки snapshot failure

Snapshot failure рідко залишається непоміченим, але його симптоми легко сплутати з іншими проблемами. Ось ключові індикатори, які вказують саме на збій snapshot:

  • Зупинка прогресу слотів після рестарту. Команда solana slot повертає одне й те саме значення протягом хвилин, тоді як сусідні вузли просуваються.
  • Повторювані спроби завантаження в логах. Валідатор циклічно намагається завантажити snapshot з різних джерел, кожна спроба завершується помилкою.
  • Високе навантаження на диск і мережу без просування. Процес agave-validator активно читає або пише, але слот не зростає — це типово для етапу розпакування, що зазнав невдачі.
  • RPC повертає застарілі дані. Якщо вузол забезпечує RPC-точку, клієнти отримують відповіді з минулих слотів або отримують помилку -32002: Slot skipped.
  • Відсутність файлу snapshot у робочій директорії. Після тривалого часу роботи директорія ledger/snapshots/ порожня або містить лише старі файли.

Критерій для відокремлення snapshot failure від інших збоїв: проблема виникає або загострюється саме після перезапуску процесу валідатора, а не під час стабільної роботи.

Типові причини

Недостатньо місця на диску

На mainnet-beta розмір повного snapshot перевищує кілька сотень гігабайтів, а після розпакування тимчасові файли можуть займати додатковий обсяг. Якщо вільного місця менше ніж розмір snapshot з запасом щонайменше 20–30%, завантаження або розпакування зазнає невдачі на середині процесу.

Перевірте реальний вільний обсяг на файловій системі, де розташований ledger:

  • df -h /path/to/ledger
  • Зверніть увагу: якщо ledger і snapshot лежать на різних розділах, перевіряте обидва.

Ризик: деякі файлові системи (зокрема ZFS без налаштованого квоти) можуть резервувати місце під метадані, тому df показує більше, ніж реально доступно для запису.

Мережева помилка при завантаженні

Валідатор завантажує snapshot за HTTP(S) з інших вузлів кластера або з генераторів snapshot. Типові мережеві проблеми:

  • Таймаут з'єднання. Джерело snapshot недоступне або перевантажене. За замовчуванням клієнт чекає обмежений час, після чого переходить до наступного джерела.
  • Обрив з'єднання (connection reset). Проміжний мережевий обладнання (firewall, NAT, load balancer) розриває довге з'єднання.
  • DNS-помилки. Валідатор не може резолвнути доменне ім'я джерела snapshot.
  • Блокування на рівні вихідного фільтрування. Порт 443 або 80 заблокований для вихідного трафіку.

Діагностичний крок: спробуйте вручну завантажити snapshot-файл з того самого URL за допомогою curl -v або wget з цього сервера і спостерігайте за поведінкою з'єднання.

Несумісність версії snapshot

Snapshot має формат, прив'язаний до версії клієнта. Якщо ви намагаєтеся завантажити snapshot, створений новішою версією Agave, ніж встановлена на вашому вузлі, валідатор відмовиться його застосовувати. Зворотна ситуація (старіший snapshot на новішому клієнті) зазвичай підтримується через механізм міграції, але це залежить від конкретних релізів — перевіряйте release notes поточної версії.

Ознака в логах: повідомлення про невідому версію формату snapshot або пряма вказівка на несумісність.

Корумпований snapshot

Файл snapshot може бути пошкоджений на будь-якому етапі: при створенні на джерелі, під час передачі через мережу або при записі на локальний диск. Agave перевіряє цілісність snapshot (хеш-сума), тому пошкоджений файл буде відхилений.

Причини корупції:

  • Асинхронний запис на диск при відключенні живлення або апаратний збій контролера.
  • Помилки оперативної пам'яті (bit flip) — рідкісно, але на великих файлах ймовірність ненульова.
  • Дефектний сектор на диску, особливо на HDD без належного моніторингу SMART.
  • Баг у файловій системі.

Діагностика через логи

Логи валідатора — це основне джерело для точної ідентифікації причини snapshot failure. Фокусуйтеся на періоді одразу після старту процесу. Типові патерни, які варто шукати:

  • "Snapshot fetch failed" або "Failed to download snapshot" — загальний індикатор невдалого завантаження. Супроводжується URL джерела і конкретною помилкою нижче по стеку.
  • "Not enough space" або "No space left on device" — пряма вказівка на проблему з місцем на диску.
  • "Snapshot version mismatch" або "Unsupported snapshot version" — несумісність версій.
  • "Snapshot integrity check failed" або "Checksum mismatch" — корумпований файл.
  • "Timeout", "Connection refused", "Connection reset by peer" — мережеві проблеми.
  • "All snapshot fetches failed" — валідатор вичерпав усі доступні джерела і не зміг отримати жоден коректний snapshot.

Практична команда для швидкого фільтру (припускаючи, що логи пишуться у файл або доступні через journald):

  • grep -i "snapshot" /path/to/validator.log | tail -100
  • Або для journald: journalctl -u agave-validator -n 500 --no-pager | grep -i snapshot

Звертайте увагу на хронологію: спочатку йдуть спроби завантаження з різних URL, потім — результат перевірки цілісності, і лише потім — фінальне рішення валідатора (відкат до синхронізації з genesis або зупинка).

Важливо: не плутайте інформаційні повідомлення про успішне створення локального snapshot (під час нормальної роботи) з повідомленнями про завантаження snapshot (під час старту). Фільтруйте за часовим проміжком, що відповідає рестарту.

Ручне завантаження snapshot з альтернативного джерела

Якщо автоматичне завантаження через механізм валідатора постійно зазнає невдачі, ви можете завантажити snapshot вручну і розмістити його у правильній директорії. Це стандартна процедура для аварійного відновлення.

Передумови: валідатор зупинений; ви знаєте версію Agave, встановлену на вузлі; у вас є доступ до альтернативного джерела snapshot (інший валідатор, архівний сервер або довірена стороння точка).

Крок 1. Визначте правильний snapshot. Перевірте, який саме snapshot потрібен вашій версії клієнта. Зверніть увагу на суфікс версії формату у назві файлу (наприклад, 123456789-XXXXXXXXXXXX-snapshot.tar.zst).

Крок 2. Завантажте файл.

  • curl -fSL -o /path/to/ledger/snapshots/snapshot.tar.zst "https://alternative-source.example.com/snapshot.tar.zst"

Прапорець -f гарантує, що curl поверне ненульовий код виходу при HTTP-помилці, а -S виведе повідомлення про помилку. Це важливо для скриптів.

Крок 3. Перевірте цілісність. Якщо джерело надає хеш-суму (SHA-256), обов'язково звірте:

  • sha256sum /path/to/ledger/snapshots/snapshot.tar.zst

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

Ризики:

  • Невідповідність версії. Якщо snapshot створений несумісною версією, валідатор проігнорує його і спробує завантажити з мережі. Перевірте release notes обох версій.
  • Недовірений джерело. Snapshot містить повний стан ledger. Завантаження з ненадійного джерела еквівалентно використанню ненадійного ledger — це пряма загроза безпеці вузла. Використовуйте лише джерела, яким ви довіряєте.
  • Застарілий snapshot. Якщо snapshot занадто старий (сотні тисяч слотів позаду), валідатор може витратити значний час на доганяння, що створить навантаження на мережу та диск.

Відкат: якщо ручне завантаження не допомогло, просто видаліть файл snapshot з директорії ledger/snapshots/ і перезапустіть валідатор — він повернеться до автоматичного механізму завантаження.

Попередження: ніколи не розпаковуйте snapshot вручну (через zstd -d) у директорію ledger. Agave очікує стиснений файл і розпаковує його сам із контролем цілісності. Розпакований файл буде проігноровано або викличе помилку.

Запобігання snapshot failures

Оперативна діагностика важлива, але системне запобігання значно дешевше за аварійне відновлення. Ось конкретні заходи, які знижують ймовірність snapshot failure до мінімуму:

  • Моніторинг вільного місця з проактивними порогами. Налаштуйте сповіщення не при 0% вільного місця, а коли вільний обсяг опускається нижче 150% розміру типового snapshot для вашого кластера. Для mainnet-beta це означає alarm рівень у сотні гігабайтів вільного місця.
  • Автоматичне очищення старих snapshot. Agave автоматично видаляє старі локальні snapshot, але якщо ви створюєте додаткові бекапи або копії, контролюйте їхній обсяг окремо.
  • Стабільна мережа з резервуванням. Якщо ваш дата-центр має проблеми з вихідною зв'язністю, розгляньте налаштування локального генератора snapshot на сусідньому вузлі тієї ж інфраструктури.
  • Синхронне оновлення версій. Оновлюйте Agave до нової версії до того, як старі snapshot стануть несумісними. Слідкуйте за release notes — там зазвичай вказується, коли старий формат snapshot перестає підтримуватися.
  • Періодична перевірка здоров'я диска. SMART-моніторинг для HDD, перевірка на bad sectors, використання файлових систем із цілісністю (ZFS, btrfs) або регулярні fsck для ext4/xfs під час планових вікон обслуговування.
  • Тестування відновлення. Періодично (раз на кілька місяців) перевіряйте, що ваш вузол успішно стартує з snapshot після перезавантаження. Це виявить латентні проблеми до того, як вони стануть критичними.

Ключовий принцип: snapshot failure майже ніколи не є випадковою подією. Практично кожен випадок можна прослідкувати до конкретної інфраструктурної вади — нестачі місця, мережевої нестабільності або пропущеного оновлення. Системне усунення цих вад робить snapshot failure передбачуваною і керованою ситуацією, а не кризою.

Джерела