theonedev/onedev · error · ExplicitException

Path '${mountPath}' should be mounted to a svg sprite resour

Error message

Path '${mountPath}' should be mounted to a svg sprite resource reference

What it means

SpriteImage resolves the SVG sprite reference by looking up the resource mapper mounted at the configured mountPath and requires it to be a SpriteResourceReference (an SVG sprite resource). If the path is mounted but points to another resource type it throws an ExplicitException; a non-mounted path yields a different path (scope == null) failure. This enforces that the resource actually contains an SVG sprite symbol registry.

Source

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

		String href = getDefaultModelObjectAsString();
		Class<?> scope;
		String symbol;
		int index = href.indexOf('#');
		if (index != -1) {
			symbol = StringUtils.strip(href.substring(index+1), "/");
			String mountPath = StringUtils.strip(href.substring(0, index), "/").trim();
			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, "/");
		}

View on GitHub (pinned to d44925c47c)

Solutions

Register the SVG sprite resource as a SpriteResourceReference and mount it at the configured path.
Update the SpriteImage mount path configuration to point at the actual sprite resource mount.
Verify with the resourceMappers list that the path's mapper resource reference is of type SpriteResourceReference.
After changing resource registration, restart/rebuild so hot-loaded classes pick up the mapper.

Example fix

// before
mountResource("/img/icons.svg", new PackageResourceReference(App.class, "icons.svg"));
// after
mountResource("/img/icons.svg", new SpriteResourceReference(App.class, "icons.svg"));

Defensive patterns

Strategy: validation

Validate before calling

boolean isSprite = Application.get().getResourceReferenceRegistry()
  .listResourceMappers().stream()
  .anyMatch(m -> ((BaseResourceMapper) m).getResourceReference() instanceof SpriteResourceReference
     && path.equals(((BaseResourceMapper) m).getPath()));

Type guard

boolean isSpriteMount(BaseResourceMapper m) { return m.getResourceReference() instanceof SpriteResourceReference; }

Try / catch

try { add(spriteImage); } catch (ExplicitException e) { if (e.getMessage().contains("svg sprite")) { fixMountPath(); } else { throw e; } }

Prevention

Keep a single constant for the sprite mount path shared by registration and SpriteImage config
Always mount sprite resources via SpriteResourceReference
Verify resource mapper registrations after refactors

When it happens

Trigger: Pointing SpriteImage's mount path (e.g. via SpriteImage.mountPath setting) at a resource mapper that is not an SVG sprite resource — e.g. a plain CSS/JS/image resource mounted at the same path.

Common situations: Configuration mistake where the sprite mount path points to a generic resource reference; refactoring resource registration so the sprite resource is no longer registered as SpriteResourceReference; copy-pasting another resource's mount path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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