What causes "An unexpected error occurred" in parcel-bundler/parcel?

Check the JS-side options object passed to package_html matches PackageOptions exactly (correct types, required fields).

parcel-bundler/parcel · error · napi::Error

GenericFailure

GenericFailure

Error message

An unexpected error occurred

What it means

Returned by the package_html napi binding (crates/node-bindings/src/html.rs) when the underlying parcel_html::package_html returns an Err. The .map_err discards the original error and substitutes a generic 'An unexpected error occurred' with Status::GenericFailure, so the JS caller loses the cause. package_html bundles transformed HTML assets into a final HTML output.

Source

Thrown at crates/node-bindings/src/html.rs:15

use napi::{Env, JsObject, JsUnknown};
use napi_derive::napi;

#[napi]
pub fn transform_html(opts: JsObject, env: Env) -> napi::Result<JsUnknown> {
  let options: parcel_html::TransformOptions = env.from_js_value(opts)?;
  let result = parcel_html::transform_html(options);
  env.to_js_value(&result)
}

#[napi]
pub fn package_html(opts: JsObject, env: Env) -> napi::Result<JsUnknown> {
  let options: parcel_html::PackageOptions = env.from_js_value(opts)?;
  let result = parcel_html::package_html(options)
    .map_err(|_| napi::Error::new(napi::Status::GenericFailure, "An unexpected error occurred"))?;
  env.to_js_value(&result)
}

#[napi]
pub fn optimize_html(opts: JsObject, env: Env) -> napi::Result<JsUnknown> {
  let options: parcel_html::OptimizeHtmlOptions = env.from_js_value(opts)?;
  let result = parcel_html::optimize_html(options)
    .map_err(|_| napi::Error::new(napi::Status::GenericFailure, "An unexpected error occurred"))?;
  env.to_js_value(&result)
}

#[napi]
pub fn transform_svg(opts: JsObject, env: Env) -> napi::Result<JsUnknown> {
  let options: parcel_html::TransformOptions = env.from_js_value(opts)?;
  let result = parcel_html::transform_svg(options);
  env.to_js_value(&result)
}

View on GitHub (pinned to 59484858a1)

Solutions

Check the JS-side options object passed to package_html matches PackageOptions exactly (correct types, required fields).
Inspect stderr/Rust logs; if unavailable, build the native crate in debug to surface the original error.
Reproduce with a minimal HTML asset set to isolate which input triggers the packager.
File an issue upstream once the underlying error is identified.

Defensive patterns

Strategy: validation

Validate before calling

function validatePackageOptions(opts) {
  if (!opts || typeof opts !== 'object') throw new TypeError('package_html options must be an object');
  // require the fields the Rust PackageOptions struct expects; adjust to current schema
  for (const key of ['assets']) if (!(key in opts)) throw new Error('Missing required option: ' + key);
}

Type guard

function isPackageOptions(v) {
  return v && typeof v === 'object' && Array.isArray(v.assets);
}

Try / catch

try {
  await package_html(opts);
} catch (e) {
  if (e?.code === 'GenericFailure' && /unexpected error/i.test(e.message)) {
    console.error('package_html failed; underlying cause was masked. Rebuild native crate with full error.');
  }
  throw e;
}

Prevention

Pass only option shapes documented for PackageOptions.
Keep JS binding version and Rust crate version in sync.
Build the native crate locally to recover masked errors during debugging.

When it happens

Trigger: parcel_html::package_html(options) returns Err — any internal failure during HTML packaging (asset assembly, source map generation, template interpolation) is masked.

Common situations: Invalid package options passed from JS, a corrupted intermediate asset graph, or a bug in the Rust HTML packager. Because the cause is swallowed, debugging requires rebuilding the native binding with the real error exposed.

Related errors

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