parcel-bundler/parcel · error · Error

Resolvers must return an absolute path, ${resolver.name} ret

Error message

Resolvers must return an absolute path, ${resolver.name} returned: ${resultFilePath}

What it means

Thrown during PathRequest resolution when a custom Resolver plugin returns a result with a filePath that is not an absolute path. Parcel's contract requires resolvers to return absolute filesystem paths so they can be reliably converted to project-relative paths via toProjectPath. The error names the offending resolver and the relative path it returned.

Source

Thrown at packages/core/core/src/requests/PathRequest.js:347

          }

          if (result.invalidateOnFileChange) {
            invalidateOnFileChange.push(...result.invalidateOnFileChange);
          }

          if (result.isExcluded) {
            return {
              assetGroup: null,
              invalidateOnFileCreate,
              invalidateOnFileChange,
              invalidateOnEnvChange,
            };
          }

          if (result.filePath != null) {
            let resultFilePath = result.filePath;
            if (!path.isAbsolute(resultFilePath)) {
              throw new Error(
                md`Resolvers must return an absolute path, ${resolver.name} returned: ${resultFilePath}`,
              );
            }

            return {
              assetGroup: {
                canDefer: result.canDefer,
                filePath: toProjectPath(
                  this.options.projectRoot,
                  resultFilePath,
                ),
                query: result.query?.toString(),
                sideEffects: result.sideEffects,
                code: result.code,
                env: dependency.env,
                pipeline:
                  result.pipeline === undefined
                    ? pipeline ?? dependency.pipeline

View on GitHub (pinned to 59484858a1)

Solutions

In your resolver plugin, use path.resolve() to ensure the returned filePath is absolute before returning.
Use options.inputFS.realpath() or the filesystem API to get an absolute resolved path.
Check the resolver plugin API docs — ResolveResult.filePath must be an absolute path.
If using a third-party resolver, check for updates or file an issue with the plugin author.
Add a defensive path.isAbsolute() check in your resolver before returning.

Example fix

// before — custom resolver plugin
export default {
  async resolve({specifier, dependency}) {
    return { filePath: `./src/${specifier}` }; // relative!
  }
};

// after
import path from 'path';
export default {
  async resolve({specifier, dependency, options}) {
    const resolved = path.resolve(options.projectRoot, 'src', specifier);
    return { filePath: resolved };
  }
};

Defensive patterns

Strategy: type-guard

Validate before calling

const path = require('path');
// In your resolver plugin, validate before returning
function validateResolverResult(result, resolverName) {
  if (result.filePath != null && !path.isAbsolute(result.filePath)) {
    throw new Error(`[${resolverName}] Resolver must return an absolute path, got: ${result.filePath}`);
  }
}

Type guard

const path = require('path');
function isResolveResultWithValidPath(result) {
  return result == null
    || result.filePath == null
    || (typeof result.filePath === 'string' && path.isAbsolute(result.filePath));
}

Prevention

Always use path.resolve() to produce absolute paths in resolver plugins.
Add a path.isAbsolute() assertion in your resolver before returning the result.
Review the Resolver plugin API contract — filePath must be absolute.

When it happens

Trigger: Inside the resolver loop in PathRequest, when result.filePath != null and path.isAbsolute(resultFilePath) is false. The resolver plugin returned a relative path (e.g., './foo.js' or 'foo.js') instead of an absolute one (e.g., '/project/src/foo.js').

Common situations: Writing a custom Parcel resolver plugin and returning a relative path by mistake; resolver uses path.join instead of path.resolve; resolver returns the module specifier as-is without full resolution; bug in a third-party resolver plugin after an API change.

Related errors

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