Errors
Package exceptions implement ExceptionInterface. Catch a precise exception
when the application can recover, or catch the interface at a request, job, or
command boundary.
| Failure | Cause | Recovery |
|---|---|---|
InvalidEntryException |
Empty specifier, or a prefix specifier whose non-null address does not end in / |
Supply a non-empty key and keep both sides of prefix mappings slash-terminated |
SpecifierNotFoundException |
No scoped, top-level, or URL-like match exists | Check spelling and add the intended mapping |
ResolutionFailedException |
An exact mapping deliberately contains null |
Remove or replace the block only when the application should permit that dependency |
JsonException |
fromJson() receives invalid JSON, or output contains bytes JSON cannot encode |
Correct the input and preserve valid UTF-8 data |
RuntimeException |
fromFile() cannot find or read its path |
Check the application-authorized path and permissions |
SpecifierNotFoundException extends ResolutionFailedException, so catching
the parent handles both missing and blocked imports. When scoped resolution is
unexpected, verify the referencing URL: the longest matching scope takes
priority, then resolution falls back through shorter scopes and top-level
imports.
The package does not verify that a resolved address exists or that a browser can fetch it. For browser failures, inspect the rendered map, document base URL, network response, and content security policy in the consuming application.