theonedev/onedev · error · ExplicitException

Unable to find svg sprite resource mounted at: ${mountPath}

Error message

Unable to find svg sprite resource mounted at: ${mountPath}

What it means

OneDev renders SVG icons via SpriteImage, which resolves an icon href of the form '<mountPath>#<symbol>'. At render time it walks the application's request mappers looking for a BaseResourceMapper whose path matches the mountPath and whose resource reference is a SpriteResourceReference. If no mapper is mounted at that path at all, it throws this ExplicitException. The purpose is to fail fast when an icon href points at a sprite resource that was never mounted.

Source

Thrown at server-core/src/main/java/io/onedev/server/web/component/svg/SpriteImage.java:99

			if (mountPath.length() != 0) {
				scope = spriteScopes.get(mountPath);
				if (scope == null) {
					List<BaseResourceMapper> resourceMappers = new ArrayList<>();
					listResourceMappers(getApplication().getRootRequestMapper(), resourceMappers);
					for (BaseResourceMapper mapper: resourceMappers) {
						BaseResourceMapper baseMapper = (BaseResourceMapper) mapper;
						if (StringUtils.strip(baseMapper.getPath(), "/").equalsIgnoreCase(mountPath)) {
							if (baseMapper.getResourceReference() instanceof SpriteResourceReference) {
								scope = baseMapper.getResourceReference().getScope();
							} else {
								throw new ExplicitException("Path '" + mountPath 
										+ "' should be mounted to a svg sprite resource reference");
							}
						}
					}
					
					if (scope == null)
						throw new ExplicitException("Unable to find svg sprite resource mounted at: " + mountPath);
					
					spriteScopes.put(mountPath, scope);
				}
			} else {
				scope = IconScope.class;
			}
		} else {
			scope = IconScope.class;
			symbol = StringUtils.strip(href, "/");
		}
		
		String spriteUrl = urlFor(new SpriteResourceReference(scope), new PageParameters()).toString();
		
		replaceComponentTagBody(markupStream, openTag, 
				"<use xlink:href='" + spriteUrl + "#" + symbol + "'></use>");
	}

	@Override

View on GitHub (pinned to d44925c47c)

Solutions

Check the href passed to SpriteImage/getVersionedHref and correct the mount path before the '#' to the built-in sprite path (usually leave it empty or use the standard icon scope path).
If it is a custom sprite, mount a SpriteResourceReference at that exact path via a BaseResourceMapper in your application/plugin init.
Verify no leading/trailing slashes or case mismatch: comparison strips slashes but is case-insensitive on path, so normalize the href.
Ensure the plugin/module that provides the sprite mount is installed and enabled.

Example fix

// before
add(new SpriteImage("icon", "/wrong-sprite/path#gear"));
// after
add(new SpriteImage("icon", "gear")); // use default icon scope sprite
// or mount custom sprite in AppPlugin init:
// mount(new BaseResourceMapper("/my-sprite", new SpriteResourceReference(MyScope.class)));

Defensive patterns

Strategy: validation

Validate before calling

// before rendering, verify the sprite mount exists
String mountPath = href.contains("#") ? StringUtils.strip(href.substring(0, href.indexOf('#')), "/") : "";
if (!mountPath.isEmpty()) {
    List<BaseResourceMapper> mappers = new ArrayList<>();
    // collect via application root request mapper as SpriteImage does
    boolean found = mappers.stream().anyMatch(m ->
        StringUtils.strip(m.getPath(), "/").equalsIgnoreCase(mountPath)
        && m.getResourceReference() instanceof SpriteResourceReference);
    if (!found) throw new IllegalStateException("No svg sprite mounted at: " + mountPath);
}

Try / catch

try {
    add(new SpriteImage("icon", href));
} catch (ExplicitException e) {
    log.warn("Bad sprite href '{}', falling back to default icon", href, e);
    add(new SpriteImage("icon", defaultSymbol));
}

Prevention

Use SpriteImage.getVersionedHref(null, symbol) or a bare symbol to rely on the default icon scope instead of hand-typed mount paths.
Centralize sprite mount paths in a constant instead of repeating string literals.
When adding custom sprites, mount SpriteResourceReference in plugin init and cover it with a smoke-test page rendering one icon.

When it happens

Trigger: A SpriteImage component (or getVersionedHref) is given an href whose mount path portion (before '#') does not correspond to any mounted resource mapper, e.g. a typo'd path, a path registered with a different mount, or a module providing the sprite that is not initialized/mounted in this instance.

Common situations: Customizing icon references in custom pages/branding with a hand-typed sprite path; upgrading OneDev where a sprite mount path changed; writing a plugin that renders icons but forgot to mount its sprite resource reference.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/271300e97252e748. Report an issue: GitHub.