What causes "ACPX provider package name is invalid: ${packageName}" in paperclipai/paperclip?

Trim the package name and reject empty strings before calling the resolver.

ACPX provider package name is invalid: ${packageName}

Error message

ACPX provider package name is invalid: ${packageName}

What it means

When the fast path `issuerRequire.resolve('<pkg>/package.json')` fails with ERR_PACKAGE_PATH_NOT_EXPORTED, resolvePackageJsonFromIssuer falls back to walking ancestor directories of the resolved entry point, splitting the package name on '/'. This error is thrown when the package name is structurally invalid: zero segments, more than two segments (invalid for scoped names), or any empty segment (e.g. leading/trailing slash or '//').

Source

Thrown at packages/paperclip-runner/src/drivers/acpx/installation-integrity.ts:369

  issuerPackageJsonPath: string,
): string {
  const issuerRequire = createRequire(issuerPackageJsonPath);
  try {
    return issuerRequire.resolve(`${packageName}/package.json`);
  } catch (error) {
    if (
      (error as NodeJS.ErrnoException).code !== "ERR_PACKAGE_PATH_NOT_EXPORTED"
    )
      throw error;
  }

  const packageSegments = packageName.split("/");
  if (
    packageSegments.length < 1 ||
    packageSegments.length > 2 ||
    packageSegments.some((segment) => segment.length === 0)
  ) {
    throw new Error(`ACPX provider package name is invalid: ${packageName}`);
  }
  let directory = dirname(realpathSync(issuerRequire.resolve(packageName)));
  for (let count = 0; count < MAX_DEPENDENCY_ANCESTORS; count += 1) {
    const matchesPackage =
      basename(directory) === packageSegments.at(-1) &&
      (packageSegments.length === 1 ||
        basename(dirname(directory)) === packageSegments[0]);
    if (matchesPackage) return resolve(directory, "package.json");
    const parent = dirname(directory);
    if (parent === directory) break;
    directory = parent;
  }
  throw new Error(
    `ACPX provider package manifest could not be located for ${packageName}`,
  );
}

function pathIsInside(root: string, candidate: string): boolean {

View on GitHub (pinned to 01ad858492)

Solutions

Trim the package name and reject empty strings before calling the resolver.
Validate with a regex like /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/ before resolving.
Fix the source string so it has at most one '/' and no empty segments.
Ensure exports in the target package include './package.json' so the fallback (and this validation) is not reached at all.

Example fix

// before
const name = `${scope}/${subpath}/`; // "@acpx/codex/" -> invalid
resolver(name, issuer);
// after
const name = `${scope}/${subpath}`;
if (!/^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name)) {
  throw new Error(`bad package name: ${name}`);
}
resolver(name, issuer);

Defensive patterns

Strategy: validation

Validate before calling

const NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
if (typeof packageName !== "string" || !NAME_RE.test(packageName)) {
  throw new Error(`invalid package name: ${packageName}`);
}

Type guard

function isValidPackageName(v: unknown): v is string {
  return typeof v === "string" &&
    v.split("/").length <= 2 &&
    v.split("/").every((s) => s.length > 0) &&
    v.length > 0;
}

Try / catch

let manifestPath: string;
try {
  manifestPath = resolver(packageName, issuer);
} catch (err) {
  if (err instanceof Error && err.message.includes("package name is invalid")) {
    throw new Error(`Fix packageName passed to ACPX resolver: "${packageName}"`);
  }
  throw err;
}

Prevention

Validate package names against npm naming rules before storing them in profiles/config.
Avoid building package names by string concatenation with paths or URLs.
Trim whitespace and strip leading/trailing slashes from user-supplied names.
Prefer adding a './package.json' export to target packages so the fallback path (and its stricter validation) is bypassed.

When it happens

Trigger: Passing a packageName with an empty segment (`"@scope/"`, `"/pkg"`, `"a//b"`), more than one slash (`"@a/b/c"`), or an empty string, to the resolver after the package's package.json subpath is not exported.

Common situations: Config or profile data with a typo'd package name; string interpolation producing a trailing slash; programmatically joined scoped names where the scope was already included once and appended again; URL-derived names containing extra path segments.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/0867c81a0e88bc35. Report an issue: GitHub.