An offline application can report plenty of available storage and still fail its next write. Quota values are estimates, other data can grow, browser policy can intervene, and a successful write today does not guarantee that the data will remain tomorrow. Design the application around completed transactions and recoverable copies.
Storage diagnostics are most useful when they answer a specific question: which origin owns the data, how much space is estimated, whether persistent treatment was granted, and what happened when the application tried to save. Keep these questions separate from whether the user has a backup.
Identify the storage boundary
The origin storage inspector reads metadata for the origin where it runs. It does not inspect another site's database. A report from this tool therefore describes this site's storage context, rather than the remaining space available to a separate offline editor.
Scheme, hostname and port help define an origin. Moving an application from one hostname to another can make its old data appear missing even though it still exists under the old origin. Development ports can create the same confusion. Record the exact URL before treating an empty database as an eviction event.
Browser partitioning can add further context for embedded storage. A third-party frame may not see the same state it sees as a top-level page. If a widget loses data only when embedded, investigate the embedding context and applicable browser storage policy before changing database code.
Read quota and usage as estimates
StorageManager.estimate can return usage and quota information when supported. Browsers may round or otherwise limit the precision of these values. The result is a planning hint, not a reservation. Another operation can consume space between the estimate and your next write.
The inspector does not open stored records or enumerate application keys. It also checks whether localStorage and sessionStorage are accessible, without reading their contents. A successful accessibility check does not show that a later large write to those interfaces will succeed.
Keep storage mechanisms distinct. Web Storage has different characteristics from IndexedDB, Cache API storage or an origin-private file system. Do not assume that subtracting reported usage from quota tells you exactly how much can be placed into one particular storage interface.
| Evidence | Useful for | Remaining limitation |
|---|---|---|
| Estimated usage and quota | Planning cache growth | Does not reserve the difference |
| persisted returns true | Understanding current eviction treatment | User deletion and device loss remain possible |
| Transaction completes | Confirming that save operation finished | Does not create an independent backup |
| Export opens correctly | Checking one recovery path | Must be repeated after format changes |
| Empty database after navigation | Starting a boundary investigation | May be a different origin or profile |
Understand persistent treatment
StorageManager.persisted reports whether the origin currently has persistent storage treatment. StorageManager.persist requests that treatment, with behaviour and grant criteria controlled by the browser. The inspector reads status but does not request a grant on the user's behalf.
Persistence can protect data from some automatic eviction decisions. It is not a promise against clearing site data, profile deletion, disk failure or application bugs. A user can still remove the data deliberately. Calling persistent storage a backup would therefore give a false impression of recoverability.
Request persistence when it fits a meaningful workflow, such as enabling an offline workspace whose data matters. Explain what is being retained. Handle a false result without blocking all use of the application, and keep an export or sync path available for important user-created content.
Plan a cache with room for the next write
Imagine an offline reader storing downloaded documents and thumbnail images. Its estimate shows 120 MiB used against a 500 MiB quota. That suggests room for growth, but it does not justify filling the remaining 380 MiB immediately. The application may need temporary space while replacing documents or updating indexes.
Separate replaceable cache data from user-created notes. Evict old thumbnails or downloaded copies according to a clear policy before deleting unsynchronised notes. Keep enough metadata to explain which items remain available offline and which will need to be downloaded again.
When a download finishes, commit its records transactionally where the storage mechanism supports it. Mark the item available only after the save completes. A success message shown before the transaction commits can leave the user relying on a document that disappears when the tab closes.
Simulate a failed write and verify the interface. The previous version should remain readable where possible, the new item should not be marked complete, and the user should receive a clear retry or export path. This test is more valuable than a dashboard showing a reassuring free-space number.
Investigate missing data without assuming the cause
First check the origin, browser profile and private-window state. Then inspect whether the user cleared site data, the application changed its database name or a migration removed records. Automatic eviction is one possibility among several, and the browser may not provide a detailed history explaining it.
Store a schema version and handle upgrades carefully. A failed migration should not silently create an empty database and report success. Preserve recoverable data, surface the failure and provide a controlled repair route. Test upgrades from real prior schemas with representative records.
If the application supports sync, distinguish locally missing data from remotely deleted data. An empty local store should not automatically become an instruction to delete every remote record. Use explicit deletion markers and conflict rules appropriate to the application.
Test recovery while the original still exists
Create a small document, add an attachment or note and export it. Import the export into a separate test profile and confirm that the content and metadata you need are present. Keep the original until the round trip succeeds. A downloaded file is not useful recovery evidence until the application can read it.
Repeat this check after changes to encryption, export formats or schema migrations. Include non-ASCII text, long names and an interrupted save in the test set. Those cases expose assumptions that a single empty sample will miss.
For an application used offline for long periods, show when data last synced and which changes exist only locally. Users need that information before clearing browser data or replacing a device. An estimated quota field does not communicate the status of their work.
Treat private contexts as temporary environments
Private browsing can impose different limits and cleanup behaviour. Do not promise that data saved there will survive after the private session ends. The exact policy varies by browser, so test your supported environments and describe the practical effect without trying to identify private mode through indirect tricks.
A useful application can still function temporarily and offer export. Keep the same honest save semantics: distinguish saved in this session from backed up elsewhere. Avoid an interface that says permanently saved merely because a storage method returned successfully.
Treat transaction completion as the save boundary
With IndexedDB, one request can succeed before the containing transaction finishes. A later request or transaction error can still prevent the intended group of changes from committing. Update the saved indicator at the transaction boundary appropriate to your operation, rather than after the first record request succeeds.
For a document with an index entry and an attachment reference, write the related records in one suitable transaction where possible. This avoids an index claiming that an attachment exists when its metadata was never committed. Large file workflows may need a more explicit staging and cleanup design.
Test an interruption between stages and reopen the application. It should recognise incomplete work, preserve the previous valid version and clean up disposable staging data. This recovery behaviour cannot be inferred from quota estimates; it must be exercised against the application's save process.
Frequently asked questions
Does quota equal free disk space?
No. Quota is a browser-managed allowance or estimate for the relevant storage context. It can depend on browser policy and the device's storage conditions. It is not a direct report of all free disk bytes, and it does not guarantee that one storage API can accept an object of that size.
Can the inspector read my documents?
This inspector reads storage metadata and accessibility information. It does not enumerate localStorage keys or open IndexedDB records. Its result therefore cannot tell you which application document occupies space. To inspect records, use the affected application's own tools or authorised browser development tools in that origin.
Should an application retry quota errors forever?
No. Repeating an unchanged write can keep failing and consume resources. Release replaceable data according to policy, offer the user a clear action and retry only when conditions change. Preserve unsaved input while explaining the failure so the user can export or move the work.
Will persistence survive clearing site data?
Persistence is not protection against deliberate removal by the user. Clearing the origin's data can remove its records and associated state. Keep independent exports or a suitable sync system for work that must survive browser cleanup, device replacement or profile corruption.
Why did a hostname change hide the old database?
The application may now be running under a different storage origin. A browser does not automatically migrate records between unrelated origins. Plan a migration while the old deployment remains accessible, with an explicit export or transfer flow that respects authentication and the user's control over their data.