Ошибка SPIFFS upload failed появляется в консоли Arduino IDE в момент вызова инструмента ESP32 Sketch Data Upload (или ESP8266 Sketch Data Upload) и означает, что образ файловой системы не смог записаться во флеш-память микроконтроллера. Чаще всего причина — не в самой плате, а в отсутствующем плагине загрузки, неверно выбранной схеме разделов или занятом последовательном порту.
Ниже разберём, как устроен процесс загрузки SPIFFS, какие проверки выполнить в первую очередь и как исправить типовые сценарии сбоя. Инструкция подходит для плат на базе ESP8266 и ESP32, работающих в среде Arduino IDE (как версии 1.x, так и 2.x), с оговорками там, где поведение версий различается.
Как работает загрузка SPIFFS и где она ломается
Файловая система SPIFFS (Serial Peripheral Interface Flash File System) хранится в отдельном разделе флеш-памяти микроконтроллера. Когда вы выбираете пункт меню загрузки данных, IDE сначала упаковывает содержимое папки data вашего скетча в бинарный образ с помощью утилиты mkspiffs, а затем передаёт его на плату через инструмент esptool (для ESP32) или esptool-ck / esptool.py (для ESP8266).
Сбой может произойти на любом из трёх этапов: плагин загрузки не установлен или не найден, образ не собирается из-за проблем с файлами, либо плата не принимает данные из-за занятого порта, неверной скорости или отсутствия режима загрузки. Поэтому диагностику имеет смысл строить по цепочке — от среды разработки к железу.
Ошибка SPIFFS upload failed — это симптом, а не диагноз. Точную причину всегда подсказывает текст ошибки в консоли чуть выше итогового сообщения.
Проверка плагина Data Upload
Наиболее частая причина — в Arduino IDE просто отсутствует плагин загрузки файловой системы. Без него пункт меню либо неактивен, либо сразу завершается ошибкой. Плагин распространяется отдельно и не входит в стандартную установку IDE.
Вам нужно проверить наличие папки с инструментом в каталоге скетчей. Для Arduino IDE 1.x путь обычно выглядит как Документы/Arduino/tools/ESP32FS/tool/esp32fs.jar (для ESP32) или .../tools/ESP8266FS/tool/esp8266fs.jar (для ESP8266). Если папки tools нет — плагин не установлен.
- 🔧 Скачайте плагин только из официального репозитория проекта (arduino-esp32 или Arduino-ESP8266 на GitHub).
- 📁 Распакуйте архив так, чтобы структура папок точно совпадала с требуемой:
tools/ESP32FS/tool/.... - 🔄 Полностью перезапустите Arduino IDE после установки — плагины подхватываются только при старте.
- 🧩 Для Arduino IDE 2.x классические плагины 1.x не работают; используйте совместимое расширение, если оно доступно для вашей версии, либо загружайте образ вручную через esptool.
⚠️ Внимание: установка плагина из сторонних непроверенных источников — риск получить устаревшую или изменённую версию утилиты. Сверяйте источник с официальной документацией ядра ESP32/ESP8266 для Arduino.
Папка data и схема разделов
Вторая типичная проблема — образ файловой системы не собирается или не влезает в выделенный раздел. Проверьте три вещи: существование папки data рядом с файлом скетча .ino, размер файлов внутри неё и выбранную схему разделов (partition scheme).
В меню Инструменты → Partition Scheme (для ESP32) выбирается схема, определяющая, сколько места отведено под SPIFFS. Если выбран вариант «No OTA» с минимальным разделом данных или схема вообще без SPIFFS-раздела, загрузка большого образа завершится ошибкой. Уменьшите суммарный размер файлов в data либо выберите схему с большим разделом файловой системы.
☑️ Проверка перед загрузкой SPIFFS
Отдельно обратите внимание на имена файлов. Кириллица, пробелы и спецсимволы в названиях файлов и подпапок могут ломать работу mkspiffs на некоторых системах. Безопасный вариант — латиница, цифры, дефис и подчёркивание.
Чтобы узнать реальный размер будущего образа, посмотрите суммарный объём файлов в папке data и сравните его с размером SPIFFS-раздела выбранной схемы — схемы описаны в документации ядра arduino-esp32.
Порт, скорость и режим загрузки
Если образ собрался, но запись на плату не проходит, проблема почти всегда в канале связи. Классический сценарий: открыт Serial Monitor в другом окне IDE или сторонняя терминальная программа удерживает COM-порт, и esptool не может получить к нему доступ.
Закройте все программы, работающие с портом, переподключите плату и повторите загрузку. Если не помогло — попробуйте снизить скорость загрузки в меню Инструменты → Upload Speed, например до 115200: дешёвые USB-UART переходники и длинные кабели не всегда стабильно работают на высоких скоростях.
Для плат, где не срабатывает автоматический перевод в режим загрузки, может потребоваться ручной вход: удерживайте кнопку BOOT, кратко нажмите EN (RST), затем отпустите BOOT — и только после этого запускайте загрузку. Наличие и расположение этих кнопок зависит от конкретной платы, поэтому сверьтесь с её документацией.
Типичные сообщения об ошибках и их расшифровка
Текст в консоли над строкой «SPIFFS Upload Failed» — главный источник информации. Ниже собраны частые варианты и их вероятные причины. Формулировки могут отличаться в зависимости от версии инструментов, поэтому ориентируйтесь на смысл, а не на дословное совпадение.
| Фрагмент ошибки | Вероятная причина | Что делать |
|---|---|---|
| SPIFFS Not Defined / partition error | В схеме разделов нет SPIFFS-раздела | Сменить Partition Scheme на вариант с SPIFFS |
| Failed to connect / timed out waiting for packet header | Плата не в режиме загрузки, занят порт, плохой кабель | Закрыть монитор порта, сменить кабель, вручную войти в boot-режим |
| Access denied / Permission denied | Порт занят другой программой или нет прав доступа (Linux) | Закрыть терминалы; на Linux проверить права на порт (группа dialout) |
| Image too large / не влезает в раздел | Образ больше размера SPIFFS-раздела | Сократить файлы в data или выбрать схему с большим разделом |
| mkspiffs не найден / error building image | Плагин установлен неполностью или неверная структура папок | Переустановить плагин, проверить путь tools/.../tool/ |
⚠️ Внимание: не перепрошивайте плату «наугад» разными схемами разделов подряд, если в SPIFFS уже хранятся важные данные (настройки, сертификаты, логи). Смена разметки и загрузка образа стирают содержимое соответствующих областей флеша.
Альтернативы: LittleFS и ручная загрузка через esptool
Стоит знать, что SPIFFS в экосистеме ESP32 считается устаревшей файловой системой, и в новых проектах рекомендуется LittleFS — она устойчивее к внезапным отключениям питания и активнее поддерживается. Для неё существуют аналогичные плагины загрузки, а принцип диагностики ошибок тот же самый.
Если плагин принципиально не работает (например, в Arduino IDE 2.x без подходящего расширения), образ можно собрать и записать вручную. Общая логика такая: сначала mkspiffs (или mklittlefs) создаёт бинарник из папки data, затем esptool записывает его по адресу начала SPIFFS-раздела. Адрес зависит от выбранной схемы разделов — его нужно брать из файла partition table вашей схемы, а не из случайных примеров.
esptool.py --chip esp32 --port COM5 write_flash АДРЕС_РАЗДЕЛА spiffs.binКоманда приведена как иллюстрация синтаксиса. Подставляйте свой порт, чип и адрес раздела из документации на используемую схему разметки — неверный адрес может затереть область приложения или загрузчика.
Почему в ESP32 рекомендуют LittleFS вместо SPIFFS
LittleFS спроектирована с учётом внезапной потери питания: структура файловой системы меньше подвержена порче при обрыве записи. SPIFFS в таких ситуациях может терять данные или требовать полного форматирования. Кроме того, развитие поддержки SPIFFS в ядре arduino-esp32 фактически остановлено, тогда как LittleFS входит в стандартную поставку. Для новых проектов миграция обычно сводится к замене подключаемой библиотеки и имени раздела в схеме.
Когда проблема в железе
Реже всего, но встречается вариант, когда программные проверки исчерпаны, а загрузка всё равно не идёт. Тогда под подозрением — USB-кабель (многие кабели от зарядок не содержат линий данных), неисправный USB-UART преобразователь на плате или нестабильное питание по USB.
Диагностика здесь простая: проверьте, прошивается ли обычный скетч (например, Blink). Если и он не загружается — проблема точно не в SPIFFS, а в связке кабель/порт/плата. Попробуйте другой кабель, другой USB-порт компьютера (лучше напрямую, без хаба) и, если есть, другую плату того же типа.
Если обычный скетч прошивается, а SPIFFS — нет, железо исправно: ищите причину в плагине, схеме разделов или папке data. Если не прошивается ничего — проблема в кабеле, порте или плате.
FAQ: частые вопросы
Arduino IDE 2.x: где пункт ESP32 Sketch Data Upload?
Во второй версии IDE классические Java-плагины от первой версии не работают. Для загрузки файловой системы нужны специальные расширения под IDE 2.x (если они доступны для вашей версии) либо ручная загрузка образа через esptool, как описано выше.
Стёрлись ли мои файлы после неудачной загрузки?
Если запись прервалась на раннем этапе, содержимое SPIFFS-раздела могло оказаться в повреждённом состоянии. Надёжный способ восстановить работоспособность — повторно загрузить корректный образ. Данные, хранившиеся только на плате, при этом восстановить обычно нельзя.
Ошибка появляется через раз, без системы — это нормально?
Плавающие сбои почти всегда указывают на нестабильный канал связи: плохой кабель, длинную линию USB, слабый порт или наводки. Снизьте скорость загрузки и замените кабель — в таких случаях это первое, что стоит сделать.
Можно ли загружать файлы на ESP32 без плагина, по Wi-Fi?
Да, если в прошивке реализована загрузка через веб-интерфейс или OTA-механизм. Это требует соответствующего кода в скетче и не является штатной функцией IDE. Для разовой записи образа проще использовать esptool.
Чем заменить SPIFFS в новом проекте?
Рекомендуемый вариант — LittleFS: она поддерживается ядром arduino-esp32, устойчивее к отключениям питания и использует тот же принцип загрузки образа из папки data. Переход обычно требует замены библиотеки и плагина загрузки.