abpframework/abp · error · CliUsageException

Invalid npm package name detected: {SanitizeForLog(packageNa

Error message

Invalid npm package name detected: {SanitizeForLog(packageName)}

What it means

Thrown by NpmHelper.EnsureSafePackageName as a command-injection guard before a package name is interpolated into an npm/npx shell command. The SafePackageNameRegex requires an npm-style name: an optional @scope/ segment followed by a package identifier, allowing only alphanumerics, dots, underscores, and hyphens. Null, empty, whitespace, or any character outside the allowed set (spaces, semicolons, pipes, quotes, etc.) triggers the exception.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Utils/NpmHelper.cs:95

        EnsureSafePackageName(package);
        EnsureSafeVersion(version);
        var packageVersion = !string.IsNullOrWhiteSpace(version) ? $"@{version}" : string.Empty;
        CmdHelper.RunCmd("npx yarn add " + package + packageVersion + " --ignore-scripts", workingDirectory: directory);
    }

    private static readonly Regex SafePackageNameRegex = new(
        @"^(@[a-zA-Z0-9][a-zA-Z0-9._-]*/)?[a-zA-Z0-9][a-zA-Z0-9._-]*$",
        RegexOptions.Compiled);

    private static readonly Regex SafeVersionRegex = new(
        @"^[a-zA-Z0-9._~^+\-]+$",
        RegexOptions.Compiled);

    public static void EnsureSafePackageName(string packageName)
    {
        if (string.IsNullOrWhiteSpace(packageName) || !SafePackageNameRegex.IsMatch(packageName))
        {
            throw new CliUsageException($"Invalid npm package name detected: {SanitizeForLog(packageName)}");
        }
    }

    public static void EnsureSafeVersion(string version)
    {
        if (!string.IsNullOrWhiteSpace(version) && !SafeVersionRegex.IsMatch(version))
        {
            throw new CliUsageException($"Invalid npm package version detected: {SanitizeForLog(version)}");
        }
    }

    public static string SanitizeForLog(string value)
    {
        if (value == null)
        {
            return "(null)";
        }

View on GitHub (pinned to 7ed43b1931)

Solutions

Pass only the package name without version (version goes in the separate version argument) and ensure it matches ^(@scope/)?name with allowed chars [A-Za-z0-9._-].
Strip whitespace and quotes from the source before calling EnsureSafePackageName.
If the value legitimately contains special characters, it is not a valid npm package name — correct the upstream data.
Treat this exception as a security stop: never bypass it by constructing the npm command manually.

Example fix

// before
helper.NpmInstallPackage("my package;rm -rf /", "1.0.0", dir);

// after — name must match ^(@[a-zA-Z0-9][a-zA-Z0-9._-]*/)?[a-zA-Z0-9][a-zA-Z0-9._-]*$
helper.NpmInstallPackage("@scope/my-package", "1.0.0", dir);

Defensive patterns

Strategy: validation

Validate before calling

using System.Text.RegularExpressions;
private static readonly Regex SafePkg = new(@"^(@[a-zA-Z0-9][a-zA-Z0-9._-]*/)?[a-zA-Z0-9][a-zA-Z0-9._-]*$", RegexOptions.Compiled);
static string EnsurePkg(string name) =>
    (string.IsNullOrWhiteSpace(name) || !SafePkg.IsMatch(name))
        ? throw new ArgumentException("Invalid npm package name") : name;

Prevention

Validate package names with the same regex before calling NpmHelper.
Never pass user input unsanitized into package-name slots; reject anything with spaces or shell metacharacters.
Keep version separate from package name (do not inline pkg@version).

When it happens

Trigger: Calling NpmInstallPackage / YarnAddPackage with a packageName that contains shell metacharacters, spaces, or is null/whitespace. The validation runs before `npm install <package>` or `npx yarn add <package>` is executed.

Common situations: User-supplied or templated package names containing spaces or special characters; a misconfigured package reference pulled from a template file; an attempt to pass a version inline (e.g. "pkg@1.0.0") into the package slot.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/57d0e52869240504. Report an issue: GitHub.