yarnpkg/yarn · error · MessageError

invalidFragment

Error message

invalidFragment

What it means

RegistryResolver's constructor tests the fragment against /^ (\S+):(@?.*?)(@(.*?)|)$/. If no match, the fragment does not conform to the <protocol>:<name>@<range> exotic format and is rejected at construction time.

Source

Thrown at src/resolvers/exotics/registry-resolver.js:17

/* @flow */

import type {Manifest} from '../../types.js';
import type PackageRequest from '../../package-request.js';
import {MessageError} from '../../errors.js';
import ExoticResolver from './exotic-resolver.js';

export default class RegistryResolver extends ExoticResolver {
  constructor(request: PackageRequest, fragment: string) {
    super(request, fragment);

    const match = fragment.match(/^(\S+):(@?.*?)(@(.*?)|)$/);
    if (match) {
      this.range = match[4] || 'latest';
      this.name = match[2];
    } else {
      throw new MessageError(this.reporter.lang('invalidFragment', fragment));
    }

    // $FlowFixMe
    this.registry = this.constructor.protocol;
  }

  static factory: Function;
  name: string;
  range: string;

  resolve(): Promise<Manifest> {
    return this.fork(this.constructor.factory, false, this.name, this.range);
  }
}

View on GitHub (pinned to c2dda503f3)

Solutions

1. Format exotic dependencies as <protocol>:<name>@<range>
2. For npm aliases, use the exact form npm:<real-name>@<semver-range>
3. Remove whitespace or illegal characters from the fragment

Example fix

// before
"aliased": "npm-real-pkg@^1.0.0"
// after
"aliased": "npm:npm-real-pkg@^1.0.0"

function isValidExoticFragment(fragment: string): boolean {
  return /^(\S+):(@?.*?)(@(.*?)|)$/.test(fragment);
}

function isWellFormedRegistryFragment(fragment: string): boolean {
  return /^(\S+):(@?.*?)(@(.*?)|)$/.test(fragment);
}

When it happens

Trigger: An exotic resolver fragment (e.g., an npm: alias) that fails the protocol/name/range regex. Constructor-time validation before resolution begins.

Common situations: Malformed npm: alias dependencies; missing protocol prefix; illegal whitespace or characters in the fragment.

Related errors

• Invalid gist fragment $0.
• Invalid hosted git fragment $0.
• Unexpected audit response (Invalid JSON): ${response}
• Unexpected audit response (Missing Metadata): ${JSON.stringi
• importResolveFailed

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/31181f609057b11b. Report an issue: GitHub.