Debugging the Filesystem API
Google Developers Logo

Progressive Web App Road Show 2016

Stopping in New York, Chicago, Austin, Toronto, Mountain View and Seattle. Learn more and sign up now.

The HTML5 Filesystem is a powerful API. With power, comes complexity. With complexity, comes more debugging frustrations. It’s an unfortunate fact that the Chrome DevTools currently do not have support for the Filesystem API. It makes debugging it more difficult than it should be. By difficult, I mean being required to write code to list/remove files in the filesystem.

During my endeavors with the Filesystem API, I picked up a couple of tips along the way that I thought I’d pass along. Each tip has its own set of limitations, but using a combination of these will get you 90% of the way. Here are the top 5:

  1. Make sure you aren’t running from file://. This is a sneaky one that a lot of people get bit by. Chrome imposes major security restrictions on file://. Many of the advanced file APIs (BlobBuilder, FileReader, Filesystem API,…) throw errors or fail silently if you run the app locally from file://. If you don’t have a web server handy, Chrome can be started with the --allow-file-access-from-files flag to bypass this security restriction. Only use this flag for testing purposes.

  2. The dreaded SECURITY_ERR or QUOTA_EXCEEDED_ERR. This usually happens when attempting to write data but you’re under the influence of #1. If that’s not the case, than it’s likely that you don’t have quota. There are two types of quota that the filesystem can be opened with, TEMPORARY or PERSISTENT. If you’re using the latter, the user needs to explicitly grant persistent storage to your app. See this post on how to do that.

  3. filesystem: URL FTW. It’s handy to open the filesystem: URL for the root DirectoryEntry of your app’s origin. What does that mean? For example, if your app lives on, open filesystem: in a new tab. Chrome will show a read-only list of the files/folders stored your app origin. For more info on filesystem: URLs, see

  4. chrome://settings/cookies is your friend. This page allows you to nuke the data stored for an origin. That includes database storage, AppCache, cookies, localStorage, and stuff in the FileSystem API. Be forewarned though, it’s an all or nothing thing. You can’t remove just one file or pieces of data.

  5. Don’t forget about error callbacks. The Filesystem API lives in an asynchronous world (unless you’re using the sync version in Workers). Always use error callback in your API calls. They’re optional, but you’ll save yourself a lot of grief later on when things blow up.

Profile photo of Eric Bidelman

Engineer @ Google working on Polymer, Chrome, and the web

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Terms of Service.