AvaloniaUI/Avalonia · critical · InvalidOperationException

Default font family name can't be null or empty.

Error message

Default font family name can't be null or empty.

What it means

GetDefaultFontFamilyName throws InvalidOperationException when the resolved default font family name is null or empty after checking options, the platform implementation, and falling back to SystemFonts[0]. This means the system could not determine ANY usable default font — the platform reported nothing and no system fonts were discovered.

Source

Thrown at src/Avalonia.Base/Media/FontManager.cs:450

            if (!ReferenceEquals(winner, candidate))
                candidate.Dispose(); // Our candidate lost the race – dispose it to avoid the leak.

            return winner;
        }

        private string GetDefaultFontFamilyName(FontManagerOptions? options)
        {
            var defaultFontFamilyName = options?.DefaultFamilyName
                ?? PlatformImpl.GetDefaultFontFamilyName();

            if (string.IsNullOrEmpty(defaultFontFamilyName) && SystemFonts.Count > 0)
            {
                defaultFontFamilyName = SystemFonts[0].Name;
            }

            if (string.IsNullOrEmpty(defaultFontFamilyName))
            {
                throw new InvalidOperationException(
                    "Default font family name can't be null or empty.");
            }

            if (defaultFontFamilyName == FontFamily.DefaultFontFamilyName)
            {
                throw new InvalidOperationException(
                    $"'{FontFamily.DefaultFontFamilyName}' is a placeholder and cannot be used as the default font family name. Provide a concrete font family name via {nameof(FontManagerOptions)} or the platform implementation.");
            }

            return defaultFontFamilyName;
        }

        void IDisposable.Dispose()
        {
            foreach (var pair in _fontCollections)
                pair.Value.Dispose();

            _fontCollections.Clear();

View on GitHub (pinned to 11c5427268)

Solutions

1. Set FontManagerOptions.DefaultFamilyName to a concrete installed font family.
2. Install fonts in the environment (e.g. apt-get install fonts-dejavu-core in Docker).
3. Ensure the platform font implementation (e.g. Skia/Win32) is correctly discovering system fonts.
4. Bundle a font as an embedded resource and reference it via an avares: FontFamily.

Example fix

// before
// FontManagerOptions.DefaultFamilyName unset, no system fonts in container

// after
services.AddSingleton<FontManagerOptions>(_ => new FontManagerOptions
{
    DefaultFamilyName = "avares://MyApp/Assets/Fonts#Inter"
});

// Ensure a concrete default is always available before FontManager initializes
var opts = new FontManagerOptions
{
    DefaultFamilyName = string.IsNullOrEmpty(configDefault) ? "DejaVu Sans" : configDefault
};

When it happens

Trigger: FontManager initialization where options.DefaultFamilyName is null/empty, PlatformImpl.GetDefaultFontFamilyName() returns null/empty, AND SystemFonts is empty. A degenerate environment with no discoverable fonts at all.

Common situations: Minimal/headless container with no fonts installed (e.g. a stripped Docker image without fontconfig/fonts). A platform implementation bug returning empty. A custom FontManagerOptions with DefaultFamilyName left unset in a font-less environment.

Related errors

• '{FontFamily.DefaultFontFamilyName}' is a placeholder and ca
• Font collection Key should follow the fonts: scheme.
• Application.Context.MainLooper was not expected to be null.
• This class should be instanciated from the UI thread
• Avalonia Application was not initialized. Make sure you have

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/97d26699ab280af9. Report an issue: GitHub.