parcel-bundler/parcel · error · Error

Could not find a .parcelrc

Error message

Could not find a .parcelrc

What it means

Thrown by loadParcelConfig() when resolveParcelConfig() returns null — meaning no .parcelrc was found in the project root (or anywhere up the tree), and no defaultConfig was available to fall back on. Parcel requires a config to know which transformers, resolvers, and namers to use.

Source

Thrown at packages/core/core/src/requests/ParcelConfigRequest.js:138

  let {config: processedConfig, cachePath} = result;
  let config = parcelConfigCache.get(cachePath);
  if (config) {
    return config;
  }

  config = new ParcelConfig(processedConfig, options);

  parcelConfigCache.set(cachePath, config);
  return config;
}

export async function loadParcelConfig(
  options: ParcelOptions,
): Promise<{|...ParcelConfigChain, usedDefault: boolean|}> {
  let parcelConfig = await resolveParcelConfig(options);

  if (!parcelConfig) {
    throw new Error('Could not find a .parcelrc');
  }

  return parcelConfig;
}

export async function resolveParcelConfig(
  options: ParcelOptions,
): Promise<?{|...ParcelConfigChain, usedDefault: boolean|}> {
  let resolveFrom = getResolveFrom(options.inputFS, options.projectRoot);
  let configPath =
    options.config != null
      ? (await options.packageManager.resolve(options.config, resolveFrom))
          .resolved
      : await resolveConfig(
          options.inputFS,
          resolveFrom,
          ['.parcelrc'],
          options.projectRoot,

View on GitHub (pinned to 59484858a1)

Solutions

1. Install the default config: npm install --save-dev @parcel/config-default.
2. Create a .parcelrc in the project root: { "extends": "@parcel/config-default" }.
3. If using the programmatic API, pass defaultConfig: '@parcel/config-default' in options.
4. In a monorepo, ensure the config package is resolvable from the directory where Parcel runs (hoist it or install locally).
5. Run npm install / yarn install to ensure node_modules is complete.

Example fix

// before — programmatic API without default config
const bundler = new Parcel({ entries: 'src/index.html' });

// after
const bundler = new Parcel({
  entries: 'src/index.html',
  defaultConfig: '@parcel/config-default',
});

const fs = require('fs');
const path = require('path');
function validateParcelConfigExists(projectRoot) {
  const parcelrc = path.join(projectRoot, '.parcelrc');
  const hasFile = fs.existsSync(parcelrc);
  // Check if @parcel/config-default is resolvable
  let hasDefault = false;
  try {
    require.resolve('@parcel/config-default', { paths: [projectRoot] });
    hasDefault = true;
  } catch {}
  if (!hasFile && !hasDefault) {
    throw new Error('No .parcelrc found and @parcel/config-default is not installed.');
  }
}

When it happens

Trigger: resolveParcelConfig() returns null when configPath is null after both the explicit config lookup (resolveConfig for .parcelrc) and the defaultConfig fallback fail. This happens when there is no .parcelrc file and options.defaultConfig is null or its resolve also fails.

Common situations: Running Parcel in a project that never had a .parcelrc and where @parcel/config-default is not installed or resolvable; monorepo where the config is at the workspace root but Parcel is run from a subdirectory without proper resolution; corrupted node_modules missing the default config package; programmatic API usage where defaultConfig was not passed.

Related errors

• Only one spread parameter can be included in a config pipeli
• Local plugins are not supported in Parcel config packages. P
• Could not find parcel config at ${path.relative(options.proj
• Failed to parse .parcelrc
• Named pipeline '${k.slice(0, i + 1)}' is reserved.

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