Errors

The five sentinel errors returned during icon resolution, and the wrapping convention for matching them.

Overview

The package defines five sentinel errors. All are package-level variables that can be matched with errors.Is. Manager and provider functions wrap these sentinels with contextual information via fmt.Errorf.

For how errors interact with fallback resolution and IgnoreNotFound, see Aliases & Fallbacks.

Sentinel errors

ErrIconNotFound

1
var ErrIconNotFound = errors.New("icon not found")

Returned by IconManager.Get when the icon name resolves to a valid provider but the provider does not have an icon with that name, and no fallback resolves.

1
import (
2
    "errors"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
_, err := manager.Get("lucide:nonexistent")
8
if errors.Is(err, swarmicons.ErrIconNotFound) {
9
    // handle missing icon
10
}

ErrProviderNotFound

1
var ErrProviderNotFound = errors.New("no provider registered for prefix")

Returned by IconManager.Get when the resolved prefix does not match any registered provider.

1
_, err := manager.Get("unknown:home")
2
if errors.Is(err, swarmicons.ErrProviderNotFound) {
3
    // no provider for prefix "unknown"
4
}

ErrInvalidIconName

1
var ErrInvalidIconName = errors.New("invalid icon name")

Returned by IconManager.Get for malformed names: empty string, empty prefix (:home), empty name (lucide:), or bare name with no default prefix set.

1
_, err := manager.Get("")
2
if errors.Is(err, swarmicons.ErrInvalidIconName) {
3
    // empty or malformed name
4
}

ErrInvalidSVG

1
var ErrInvalidSVG = errors.New("invalid SVG content")

Returned by FromFile and FromString when the input is empty or contains no <svg> element. Also returned internally when an Iconify JSON entry has an empty body.

1
_, err := swarmicons.FromString("")
2
if errors.Is(err, swarmicons.ErrInvalidSVG) {
3
    // empty or unparseable SVG
4
}

ErrProviderError

1
var ErrProviderError = errors.New("provider error")

Returned by provider constructors for infrastructure-level failures: NewDirectoryProvider when the directory does not exist, NewJsonCollectionProvider when the file cannot be read, and FromFile on I/O errors.

1
_, err := swarmicons.NewDirectoryProvider("/nonexistent")
2
if errors.Is(err, swarmicons.ErrProviderError) {
3
    // directory does not exist
4
}

Wrapping convention

Manager methods wrap sentinel errors with the original name for context:

1
fmt.Errorf("get %q: %w", name, ErrProviderNotFound)

This preserves errors.Is matching while adding the icon name to the error message:

1
get "unknown:home": no provider registered for prefix

Always use errors.Is for matching, not string comparison:

1
import (
2
    "errors"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
_, err := manager.Get("unknown:home")
8
if errors.Is(err, swarmicons.ErrProviderNotFound) {
9
    // correct: matches wrapped errors
10
}
11
12
// WRONG: do not compare error strings
13
if err.Error() == "no provider registered for prefix" {
14
    // fails because the error is wrapped with context
15
}

See also

• Aliases & Fallbacks: IgnoreNotFound() behavior and fallback resolution
• IconManager API reference: the Get() method that produces these errors

Summary table