{"record":{"id":"97d26699ab280af9","repo":"AvaloniaUI/Avalonia","slug":"default-font-family-name-can-t-be-null-or-empty","errorCode":null,"errorMessage":"Default font family name can't be null or empty.","messagePattern":"Default font family name can't be null or empty\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"src/Avalonia.Base/Media/FontManager.cs","lineNumber":450,"sourceCode":"            if (!ReferenceEquals(winner, candidate))\n                candidate.Dispose(); // Our candidate lost the race – dispose it to avoid the leak.\n\n            return winner;\n        }\n\n        private string GetDefaultFontFamilyName(FontManagerOptions? options)\n        {\n            var defaultFontFamilyName = options?.DefaultFamilyName\n                ?? PlatformImpl.GetDefaultFontFamilyName();\n\n            if (string.IsNullOrEmpty(defaultFontFamilyName) && SystemFonts.Count > 0)\n            {\n                defaultFontFamilyName = SystemFonts[0].Name;\n            }\n\n            if (string.IsNullOrEmpty(defaultFontFamilyName))\n            {\n                throw new InvalidOperationException(\n                    \"Default font family name can't be null or empty.\");\n            }\n\n            if (defaultFontFamilyName == FontFamily.DefaultFontFamilyName)\n            {\n                throw new InvalidOperationException(\n                    $\"'{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.\");\n            }\n\n            return defaultFontFamilyName;\n        }\n\n        void IDisposable.Dispose()\n        {\n            foreach (var pair in _fontCollections)\n                pair.Value.Dispose();\n\n            _fontCollections.Clear();","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/AvaloniaUI/Avalonia/blob/11c542726898ae954a1ef668c65ec79ec92ab17d/src/Avalonia.Base/Media/FontManager.cs#L432-L468","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set FontManagerOptions.DefaultFamilyName to a concrete installed font family.","Install fonts in the environment (e.g. apt-get install fonts-dejavu-core in Docker).","Ensure the platform font implementation (e.g. Skia/Win32) is correctly discovering system fonts.","Bundle a font as an embedded resource and reference it via an avares: FontFamily."],"exampleFix":"// before\n// FontManagerOptions.DefaultFamilyName unset, no system fonts in container\n\n// after\nservices.AddSingleton<FontManagerOptions>(_ => new FontManagerOptions\n{\n    DefaultFamilyName = \"avares://MyApp/Assets/Fonts#Inter\"\n});","handlingStrategy":"fallback","validationCode":"// Ensure a concrete default is always available before FontManager initializes\nvar opts = new FontManagerOptions\n{\n    DefaultFamilyName = string.IsNullOrEmpty(configDefault) ? \"DejaVu Sans\" : configDefault\n};","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set FontManagerOptions.DefaultFamilyName to a known-installed font in headless/CI containers.","Install base font packages (e.g. fonts-dejavu-core) in Docker images.","Bundle an embedded font resource as a guaranteed fallback."],"tags":["font-manager","configuration","media","fonts","headless","platform"],"backgroundTag":null,"analyzedSha":"11c542726898ae954a1ef668c65ec79ec92ab17d","analyzedAt":"2026-08-13T11:57:40.261Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}