parcel-bundler/parcel · error · Error

IDBCache is only supported in the browser

Error message

IDBCache is only supported in the browser

What it means

IDBCache is a Cache implementation backed by IndexedDB, which exists only in browsers. The constructor throws immediately so the failure surfaces at instantiation rather than silently corrupting in Node. This class is only meant to be constructed in a browser runtime; importing the module in Node is fine, but constructing it is not.

Source

Thrown at packages/core/cache/src/IDBCache.js:7

// @flow strict-local
import type {Cache} from './types';

// $FlowFixMe
export class IDBCache implements Cache {
  constructor() {
    throw new Error('IDBCache is only supported in the browser');
  }
}

View on GitHub (pinned to 59484858a1)

Solutions

1. Only instantiate IDBCache inside code that runs in the browser (guard with `typeof indexedDB !== 'undefined'`).
2. Use the default filesystem cache (or another Node-compatible Cache) on the server.
3. Dynamically import IDBCache from a browser-only entry point so it never loads in Node.

Example fix

// before
import {IDBCache} from '@parcel/cache';
const cache = new IDBCache();

// after
import {FSCache} from '@parcel/cache';
const cache = typeof indexedDB !== 'undefined'
  ? new (await import('@parcel/cache')).IDBCache()
  : new FSCache(cacheDir);

// Before constructing, confirm a browser IndexedDB is present.
const hasIDB = typeof indexedDB !== 'undefined' && indexedDB !== null;
const cache = hasIDB ? new IDBCache() : fallbackNodeCache();

function isBrowserWithIDB(): boolean {
  return typeof indexedDB !== 'undefined' && indexedDB !== null;
}

When it happens

Trigger: Calling `new IDBCache()` (or passing it as `options.cache`) in Node.js, jsdom, SSR, or any runtime without a real IndexedDB implementation.

Common situations: Sharing cache code between browser and server bundles; running unit tests under Node; server-side rendering that imports browser-only modules.

Related errors

• NodeFS isn't available in the browser
• Responding to file system events exceeded threshold, start w
• Cannot change an asset's uniqueKey after it has been set.
• Unknown environment feature: ${feature}
• Config result is not hashable because it contains non-serial

AI-assisted analysis of parcel-bundler/parcel@59484858a1 (2026-08-13). Data as JSON: /api/errors/4d5556dc68ca3a2e. Report an issue: GitHub.