alibaba/nacos · critical · NacosApiException

SERVER_ERROR

SERVER_ERROR

Error message

visibility grant management is unsupported in current runtime

What it means

Thrown by DefaultVisibilityGrantService.requireManagedResource() when no VisibilityResourceLocator SPI bean is found in the Spring application context. The locator is responsible for finding resources (configs, services, etc.) that visibility grants can be attached to. Its absence means the current runtime mode does not support visibility grant management — typically because the server is running in a mode or module that doesn't register a locator.

Source

Thrown at plugin-default-impl/nacos-default-auth-plugin/src/main/java/com/alibaba/nacos/plugin/auth/impl/visibility/DefaultVisibilityGrantService.java:202

                || !normalizedResourceType.equals(parsed.getResourceType())) {
                continue;
            }
            if (VisibilityGrantRoleHelper.matchesRequestedAction(permission.getAction(),
                action)) {
                names.add(parsed.getResourceName());
            }
        }
        return new ArrayList<>(names);
    }
    
    private VisibilityResource requireManagedResource(String namespaceId, String resourceType,
        String resourceName) throws NacosException {
        validateResourceTypeAndName(resourceType, resourceName);
        AtomicReference<VisibilityResourceLocator> locatorRef = new AtomicReference<>();
        ApplicationUtils.getBeanIfExist(VisibilityResourceLocator.class, locatorRef::set);
        VisibilityResourceLocator locator = locatorRef.get();
        if (locator == null) {
            throw new NacosApiException(NacosException.SERVER_ERROR, ErrorCode.SERVER_ERROR,
                "visibility grant management is unsupported in current runtime");
        }
        Optional<VisibilityResource> resource =
            locator.findResource(VisibilityGrantRoleHelper.normalizeNamespaceId(namespaceId),
                VisibilityGrantRoleHelper.normalizeResourceType(resourceType), resourceName);
        return resource.orElseThrow(() -> new NacosApiException(NacosException.NOT_FOUND,
            ErrorCode.RESOURCE_NOT_FOUND,
            "resource not found: " + resourceName));
    }
    
    private void checkManageGrantAuthority(VisibilityResource resource) throws NacosException {
        // Allow access rules: 1. Authentication not enabled; 2. Global administrator; 3. Resource owner.
        if (!NacosAuthConfigHolder.getInstance().isAnyAuthEnabled()) {
            return;
        }
        String currentUsername = AuthIdentityUtils.resolveCurrentUsername();
        if (AuthIdentityUtils.isCurrentIdentityGlobalAdmin(currentUsername)) {
            return;

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Verify that the appropriate module (e.g. console or the resource-owning module) is included in the deployment and registers a VisibilityResourceLocator bean.
2. Check Spring bean initialization logs for VisibilityResourceLocator — if it failed to construct, fix the underlying bean creation error.
3. Ensure the server is running in a deployment mode that supports visibility features (not a stripped-down or test mode).
4. If using a custom plugin architecture, confirm your VisibilityResourceLocator SPI implementation is on the classpath and properly annotated/configured.

Example fix

// Ensure a VisibilityResourceLocator bean is registered, e.g. via @Component or @Bean:
@Component
public class MyResourceLocator implements VisibilityResourceLocator {
    @Override
    public Optional<VisibilityResource> findResource(String namespaceId,
        String resourceType, String resourceName) {
        // lookup logic
    }
}

// Check for locator availability before calling visibility operations
VisibilityResourceLocator locator = ApplicationUtils.getBean(VisibilityResourceLocator.class);
if (locator == null) {
    throw new IllegalStateException(
        "Visibility grant management is not available — no VisibilityResourceLocator registered");
}

public static boolean isVisibilityGrantSupported() {
    try {
        return ApplicationUtils.getBean(VisibilityResourceLocator.class) != null;
    } catch (Exception e) {
        return false;
    }
}

try {
    service.grant(namespaceId, resourceType, resourceName, username, action);
} catch (NacosApiException e) {
    if (e.getErrCode() == NacosException.SERVER_ERROR
        && e.getMessage().contains("unsupported in current runtime")) {
        // visibility feature not available in this deployment
        log.error("Visibility grants are not supported in this runtime mode");
    }
    throw e;
}

When it happens

Trigger: Calling grant(), revoke(), or findAuthorizedResourceNames() on DefaultVisibilityGrantService when the Spring context has no VisibilityResourceLocator bean registered. This happens when the visibility feature is not fully initialized or the server is in a deployment mode that doesn't include resource locator SPI implementations.

Common situations: Running a minimal/embedded Nacos server without the full console module; a plugin or module that should register VisibilityResourceLocator failed to load; Spring context refresh ordering issue where the locator bean hasn't been created yet; running in a test or development mode without the full plugin stack.

Related errors

• ACCESS_DENIED
• PARAMETER_MISSING
• PARAMETER_VALIDATE_ERROR
• SERVER_ERROR
• action is blank

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/4bf6ca8e30da7ea2. Report an issue: GitHub.