AvaloniaUI/Avalonia · error · ArgumentException

Font collection Key should follow the fonts: scheme.

Error message

Font collection Key should follow the fonts: scheme.

What it means

FontManager.AddFontCollection throws ArgumentException when the font collection's Key URI does not use the 'fonts' scheme (FontCollectionScheme == "fonts"). Custom font collections must be registered under a 'fonts:' URI so the manager can route lookups correctly. The check uses UriExtensions.IsFontCollection which compares uri.Scheme == "fonts".

Source

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

            glyphTypeface = null;

            return false;
        }

        /// <summary>
        /// Add a font collection to the manager.
        /// </summary>
        /// <param name="fontCollection">The font collection.</param>
        /// <exception cref="ArgumentException"></exception>
        /// <remarks>If a font collection's key is already present the collection is replaced.</remarks>
        public void AddFontCollection(IFontCollection fontCollection)
        {
            var key = fontCollection.Key;

            if (!fontCollection.Key.IsFontCollection())
            {
                throw new ArgumentException("Font collection Key should follow the fonts: scheme.", nameof(fontCollection));
            }

            _fontCollections.AddOrUpdate(key, fontCollection, (_, oldCollection) =>
            {
                oldCollection.Dispose();

                return fontCollection;
            });
        }

        /// <summary>
        /// Removes the font collection that corresponds to specified key.
        /// </summary>
        /// <param name="key">The font collection's key.</param>
        public void RemoveFontCollection(Uri key)
        {
            if (_fontCollections.TryRemove(key, out var fontCollection))
            {

View on GitHub (pinned to 11c5427268)

Solutions

1. Set the IFontCollection.Key to a URI with the 'fonts' scheme, e.g. new Uri("fonts:MyCollection").
2. Verify uri.Scheme == "fonts" (FontManager.FontCollectionScheme) before calling AddFontCollection.
3. If wrapping built-in collections, follow the same Key convention used by SystemFonts (which uses a fonts: scheme).

Example fix

// before
collection.Key = new Uri("custom:MyFonts", UriKind.Absolute);
manager.AddFontCollection(collection);

// after
collection.Key = new Uri("fonts:MyFonts", UriKind.Absolute);
manager.AddFontCollection(collection);

if (collection.Key.Scheme != FontManager.FontCollectionScheme) // "fonts"
    throw new InvalidOperationException($"Key scheme must be 'fonts', got '{collection.Key.Scheme}'.");
manager.AddFontCollection(collection);

When it happens

Trigger: Calling fontManager.AddFontCollection(collection) where collection.Key is a Uri whose Scheme is not exactly "fonts". E.g. Key = new Uri("http://...", ...), new Uri("avares://...", ...), or a relative URI.

Common situations: Implementing a custom IFontCollection and setting Key to a non-fonts scheme. Copy-pasting a URI scheme from another context. Misreading the contract and using the application asset scheme instead of 'fonts:'.

Related errors

• File path is expected to be an absolute link with "file" or
• Folder path is expected to be an absolute link with "file" o
• Base uri must be an absolute uri.
• Default font family name can't be null or empty.
• '{FontFamily.DefaultFontFamilyName}' is a placeholder and ca

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