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.

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

• ' ' is a placeholder and cannot be used as the default font…
• Font collection Key should follow the fonts: scheme.
• Activity.Window must be set.
• Animator has no property specified.
• Animator has no property specified.

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

Appendix: 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)