abpframework/abp · error · CliUsageException

Invalid npm package version detected: {SanitizeForLog(versio

Error message

Invalid npm package version detected: {SanitizeForLog(version)}

What it means

Thrown by NpmHelper.EnsureSafeVersion, the version counterpart to the package-name guard. SafeVersionRegex allows only [A-zA-Z0-9._~^+-], which covers semver, caret/tilde ranges, and pre-release tags. A null/whitespace version is allowed (optional), but any other character (spaces, comparison operators, shell metacharacters) throws a CliUsageException before the value is concatenated into the shell command.

Source

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

        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)";
        }

        return Regex.Replace(value, @"[\x00-\x1F\x7F]", "?");
    }

    public string GetInstalledNpmPackages()
    {
        Logger.LogInformation("Checking installed npm global packages...");
        return CmdHelper.RunCmdAndGetOutput("npm list -g --depth 0 --silent", out int exitCode);
    }

View on GitHub (pinned to 7ed43b1931)

Solutions

Pass a plain semver value or a caret/tilde range with no spaces, e.g. "1.2.3", "^1.0.0", "~2.1.0", "1.0.0-beta.1".
Omit the version (pass null/empty) to install the latest.
Trim and validate the version source before passing it; reject anything with spaces or shell metacharacters upstream.

Example fix

// before
helper.YarnAddPackage("lodash", ">= 4.0.0 < 5", dir);

// after — use caret/tilde range without spaces
helper.YarnAddPackage("lodash", "^4.17.0", dir);

Defensive patterns

Strategy: validation

Validate before calling

using System.Text.RegularExpressions;
private static readonly Regex SafeVer = new(@"^[a-zA-Z0-9._~^+\-]+$", RegexOptions.Compiled);
static string EnsureVer(string? version) =>
    string.IsNullOrWhiteSpace(version) ? version! :
    !SafeVer.IsMatch(version) ? throw new ArgumentException("Invalid npm version") : version;

Prevention

Pass only plain semver or caret/tilde ranges with no spaces.
Trim version strings from config before use.
Omit version when latest is acceptable.

When it happens

Trigger: Calling NpmInstallPackage / YarnAddPackage with a version string containing spaces, comparison operators (>=, <), or shell metacharacters; or a version pulled from untrusted input.

Common situations: Passing a full npm version range with spaces like ">= 1.0.0 < 2.0.0"; templating a version from a config file that includes surrounding quotes or whitespace; copy-pasting a version specifier with a leading 'v'.

Related errors

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