What causes "Content part name contains invalid characters" in OrchardCMS/OrchardCore?

Replace invalid characters: use PascalCase with no spaces ('OrderDetails')

OrchardCMS/OrchardCore · error · ArgumentException

Content part name contains invalid characters

Error message

Content part name contains invalid characters

What it means

ContentTypeDefinitionBuilder's inner Build() also rejects part names whose value differs from their ToSafeName() result, i.e. names containing spaces, punctuation, or other unsafe characters. Safe names are required for reliable use in placement, drivers, and generated UI.

Solutions

Replace invalid characters: use PascalCase with no spaces ('OrderDetails')
Run the candidate name through ToSafeName() and compare before calling WithPart
Put the human-readable label in the part's display name / settings instead of the technical name

Example fix

// before
builder.AlterTypeDefinitionAsync("Order", t => t.WithPart("Order Details"));
// after
builder.AlterTypeDefinitionAsync("Order", t => t.WithPart("OrderDetails"));

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(partName) || !string.Equals(partName, partName.ToSafeName(), StringComparison.OrdinalIgnoreCase))
    throw new ArgumentException($"Part name '{partName}' contains invalid characters.");

Try / catch

try
{
    await builder.AlterTypeDefinitionAsync(typeName, t => t.WithPart(partName));
}
catch (ArgumentException ex) when (ex.Message.Contains("invalid characters"))
{
    _logger.LogError(ex, "Part name '{Name}' is not a safe name", partName);
}

Prevention

Use PascalCase technical part names; put spaces only in display labels
Run names through ToSafeName() in code that generates parts dynamically
Watch for invisible whitespace when names come from config or spreadsheets

When it happens

Trigger: Calling WithPart with names like 'Order Details', 'Billing/Shipping', or names containing dots or unicode characters during type alteration

Common situations: Using display-style names ('Order Details') as technical part names; deriving part names from database column names with spaces; copy-pasted names with invisible whitespace

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/c6618c8ec5a39123. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.ContentManagement.Abstractions/Metadata/Builders/ContentTypeDefinitionBuilder.cs:219

        private readonly ContentPartDefinition _partDefinition;

        public PartConfigurerImpl(ContentTypePartDefinition part)
            : base(part)
        {
            Current = part;
            _partDefinition = part.PartDefinition;
        }

        public override ContentTypePartDefinition Build()
        {
            if (!char.IsLetter(Current.Name[0]))
            {
                throw new ArgumentException("Content part name must start with a letter", "name");
            }

            if (!string.Equals(Current.Name, Current.Name.ToSafeName(), StringComparison.OrdinalIgnoreCase))
            {
                throw new ArgumentException("Content part name contains invalid characters", "name");
            }

            return new ContentTypePartDefinition(Current.Name, _partDefinition, _settings)
            {
                ContentTypeDefinition = Current.ContentTypeDefinition,
            };
        }
    }
}

View on GitHub (pinned to 4306c0717f)