Unable to build and upload SPIFFS filesystem image with framework esp-idf

Hi everyone,

I am new to PlatformIO and I need some help on building and uploading SPIFFS filesystem image to my ESP32 board.

Let me throw my find first.

  1. I am able to build and upload SPIFFS to my ESP32 board with Arduino framework
  2. I am unable to build and upload SPIFFS to my ESP32 board with ESP-IDF framework

The Arduino project I created is following this link

The ESP-IDF project I created is following this link

For both project, I created a folder “data” and put the same file called “index.html”.
And here is my screenshot for ESP-IDF project

There is no error message telling me what exactly it is failing to build and upload to the ESP32.
I have no idea how to troubleshoot this issue.

Thank you in advance if someone could help me.

Did you find a solution to this? I’m hitting the same problem and the same errors.

You need to do as the Espressif Docs say.

First, you need a partition table that allows some storage for SPIFFS files. The default one, partitions_singleapp.csv, has no spiffs partition (see PlatformIO docs). So, I copied that file into my project and, adapting from the Arduino file here,

I wrote my partitions_custom.csv as

# Name,   Type, SubType, Offset,  Size, Flags
# Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap
nvs,      data, nvs,     ,        0x6000,
phy_init, data, phy,     ,        0x1000,
factory,  app,  factory, ,        1M,
spiffs,   data, spiffs,  ,        1M

for a 1MB SPIFFS into the root of my project folder.

Further I need to tell PlatformIO and the ESP-IDF tools that that is now my partition table, so I add

board_build.partitions = partitions_custom.csv

to my platformio.ini and use the “Run Menuconfig” project task to go into “Partition Table” and change it to a custom partition with the file name I have chosen.

And I quit-and-save out of that. Further, as per docs linked above, I now modify the CMakeLists.txt file in the root of my project to tell it that I want to build the SPIFFS partition binary from a certain folder in my project, by adding

spiffs_create_partition_image(spiffs data)

and the bottom to fill the spiffs partition with the files from data. I then create a data folder in my project and put in a index.html with some file content.

I use the project task “Build Filesystem Image” and…

it works.

And then I can flash it to my ESP32 with “Upload Filesystem Image”…

and that nicely works too.

Notice the offset Writing at 0x00107000... is correct. Sum up the sizes in the partition table of 0x6000, 0x1000 and 1MB (=0x100000) and you receive 0x107000.

So with that configuration per Espressif docs, all is well.


Hi maxgerhardt,

Thank you for your reply.
I figured out the same solution after turning to official ESP-IDF VSCode extension.
If it can detect missing the partition table, it will help new user locating the root cause.


I’ve opened the issue Add example for ESP-IDF + SPIFFS usage · Issue #472 · platformio/platform-espressif32 · GitHub so that we may have a reference example and better docs.

Edit: We actually already refer to an ESP-IDF project in the official docs – Espressif 32 — PlatformIO latest documentation

Hi max, I have 2 questions please,

1- how I can get my project tasks menu (especially platform) to be like yours?

mine doesn’t contain the Menuconfig nor the Upload Filestsytem Image

2- I followed what Espressif said and created a directory (same level as src) and i mounted a SPIFFS partition into the project and it is mounted successfully

My issue (as i think) is that the file is not uploaded to the portion as it always gives a"NULL" when i try to read the file

This is the project CMakeLists.txt file (i tried to modify it as yours in this thread, both definitions for create_partition_image don’t work.

Thank you in advance

Was a solution to this ever found? I am missing the whole of the Platform menu and so can’t do a Build Filesystem Image.

I’m running OS/X, trying to upload things to an ESP32 using VS Code/PlatformIO/SPIFFS and am completely stuck. Any help would be appreciated.

Do you also have the CMake and ESP-IDF extension installed besides PlatformIO? Does it work without them? I feel like these interfere.

Not as far as I know, Max. The Extensions window on my VS Code/PlatformIO screen shows Arduino, C/C++, Jupyter, markdownlint, PlatformIO IDE and Python. I haven’t explicitly installed any of those, other than PlatformIO and Python.

For the time being, I’m using the solution mentioned earlier - setting up a dummy Arduino .ino file with a data sub-folder and then using my Arduino app’s Sketch Data Upload facility - but this is cumbersome, doing half the work in PlatformIO and half in Arduino, since this seemed to involve closing one app and opening the other at each stage, to avoid “port in use”-type messages.

Any other thoughts?

Thanks & regards,

Is the behavior the same on the official ESP-IDF + SPIFFS example? Does disabling the Arduino extension make a difference?

With thanks to Sara Santos at RandomNerdTutorials.com, an answer which has worked for me is as follows:

With your project opened in VS Code, go to View > Pallete . Then, write: >Refresh project tasks and select that option as shown below.”

(And thanks to Max for your suggestions.)


Finally, check for updates.

Then, check if the Platform Tasks to upload an image to the filesystem were updated.

I didn’t get around to trying this, Max, since Sara Santos supplied a solution which allowed me to progress with my task of working through one of the Random Nerd Tutorial eBooks on ESP32 Webservers. Thanks anyway.

Btw, the Arduino extension conflicts with PlatformIO as per

so I’m pretty sure that’s the culprit here.