What causes "The file extension should start with a dot." in OrchardCMS/OrchardCore?

Prefix the extension with a dot: ".pdf" instead of "pdf".

OrchardCMS/OrchardCore · error · ArgumentException

The file extension should start with a dot.

Error message

The file extension should start with a dot.

What it means

MediaFileIndexingOptions validates that every registered file extension key starts with a dot so extension lookups are normalized. Registering an extension like "pdf" instead of ".pdf" throws ArgumentException at registration time.

Solutions

Prefix the extension with a dot: ".pdf" instead of "pdf".
Normalize keys at configuration load time: if (!ext.StartsWith('.')) ext = "." + ext;
Check startup logs/options validation to find the offending extension key.

Example fix

// before
services.Configure<MediaFileIndexingOptions>(o => o.TextProviders["pdf"] = myProvider);
// after
services.Configure<MediaFileIndexingOptions>(o => o.TextProviders[".pdf"] = myProvider);

Defensive patterns

Strategy: validation

Validate before calling

if (!fileExtension.StartsWith('.'))
    fileExtension = "." + fileExtension.TrimStart('*');

Type guard

static bool IsValidFileExtension(string ext) => !string.IsNullOrEmpty(ext) && ext.StartsWith('.');

Try / catch

catch (ArgumentException ex) when (ex.Message.Contains("file extension should start with a dot"))
{
    // normalize the key and retry registration
}

Prevention

Normalize extension keys to dotted lowercase form at config load.
Derive extensions from Path.GetExtension (which keeps the dot), not string splits.
Add options validation on startup to fail fast on undotted keys.

When it happens

Trigger: Calling RegisterMediaFileTextProvider (or configuring MediaFileTextProviders options) with a dictionary key such as "pdf", "TXT", or "md" that lacks the leading dot.

Common situations: Copy-pasting extension names from filenames ("document.pdf") or MIME types without normalizing; building options programmatically from a list of extensions formatted without dots.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Media.Abstractions/Indexing/MediaFileIndexingOptions.cs:35

        return this;
    }

    public Type GetRegisteredMediaFileTextProvider(string fileExtension)
    {
        if (_mediaFileTextProviderRegistrations.TryGetValue(ValidateFileExtension(fileExtension), out var providerType))
        {
            return providerType;
        }

        return null;
    }

    private static string ValidateFileExtension(string fileExtension)
    {
        if (!fileExtension.StartsWith('.'))
        {
            throw new ArgumentException("The file extension should start with a dot.");
        }

        return fileExtension;
    }
}

View on GitHub (pinned to 4306c0717f)