abpframework/abp · error · CliUsageException

Project name cannot contain surrogate or control characters!

Error message

Project name cannot contain surrogate or control characters! Specify a different name.

What it means

Thrown by ProjectNameValidator.ValidateSurrogateOrControlChar when the project name contains any Unicode control character (char.IsControl) or surrogate (char.IsSurrogate). Surrogates alone are invalid as a filename component, and control characters can corrupt terminals and the filesystem.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Utils/ProjectNameValidator.cs:37

    private static readonly string[] IllegalKeywords = new[]
    {
            "MauiBlazor",
            "Blazor"
    };

    private static void ValidateParentDirectoryString(string projectName)
    {
        if (projectName.Contains(".."))
        {
            throw new CliUsageException("Project name cannot contain \"..\"! Specify a different name.");
        }
    }

    private static void ValidateSurrogateOrControlChar(string projectName)
    {
        if (projectName.Any(chr => char.IsControl(chr) || char.IsSurrogate(chr)))
        {
            throw new CliUsageException("Project name cannot contain surrogate or control characters! Specify a different name.");
        }
    }

    private static void ValidateIllegalProjectName(string projectName)
    {
        foreach (var illegalProjectName in IllegalProjectNames)
        {
            if (projectName.Equals(illegalProjectName, StringComparison.OrdinalIgnoreCase))
            {
                throw new CliUsageException("Project name cannot be \"" + illegalProjectName + "\"! Specify a different name.");
            }
        }
    }

    private static void ValidateIllegalKeywords(string projectName)
    {
        foreach (var illegalKeyword in IllegalKeywords)
        {

View on GitHub (pinned to 7ed43b1931)

Solutions

Strip control and surrogate characters from the name before passing it; prefer plain ASCII alphanumerics and dots.
Sanitize the source (trim newlines, remove BOM) if the name comes from a file or external input.
Run ProjectNameValidator.Validate() early in custom tooling to fail with a clean message.

Example fix

// before — name from a file with a trailing newline: "MyApp\n"
// after
var name = rawName.Where(c => !char.IsControl(c) && !char.IsSurrogate(c)).ToArray();
var cleanName = new string(name);

Defensive patterns

Strategy: validation

Validate before calling

static string CleanName(string raw)
{
    var clean = new string(raw.Where(c => !char.IsControl(c) && !char.IsSurrogate(c)).ToArray());
    Volo.Abp.Cli.Utils.ProjectNameValidator.Validate(clean);
    return clean;
}

Prevention

Sanitize names from files/input: strip BOM, CR/LF, control codes, lone surrogates.
Prefer plain ASCII names for projects.
Validate early in any wrapper that programmatically calls `abp new`.

When it happens

Trigger: Passing a project name with embedded control codes (e.g. tab, newline, BEL) or lone surrogate code points. This is the first validation run by Validate(), before the ".." and illegal-name checks.

Common situations: Project name read from a config file with stray CR/LF or BOM; name assembled from user input that included an emoji or astral-plane character split into surrogate halves; clipboard paste introducing invisible control characters.

Related errors

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