{"record":{"id":"6dade06c8ad8e189","repo":"alibaba/nacos","slug":"500-6dade0","errorCode":"500","errorMessage":"Spring MVC RequestMappingHandlerMapping is unavailable","messagePattern":"Spring MVC RequestMappingHandlerMapping is unavailable","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":500,"severity":"critical","filePath":"core/src/main/java/com/alibaba/nacos/core/code/ControllerMethodsCache.java","lineNumber":126,"sourceCode":"    public Method getMethod(HttpServletRequest request) {\n        if (handlerMappingProvider != null && !isLegacyResolverEnabled()) {\n            return getMethodFromHandlerMapping(request);\n        }\n        return getMethodFromLegacyCache(request);\n    }\n    \n    private boolean isLegacyResolverEnabled() {\n        String systemProperty = System.getProperty(LEGACY_RESOLVER_ENABLED);\n        if (systemProperty != null) {\n            return Boolean.parseBoolean(systemProperty);\n        }\n        return EnvUtil.getProperty(LEGACY_RESOLVER_ENABLED, Boolean.class, false);\n    }\n    \n    private Method getMethodFromHandlerMapping(HttpServletRequest request) {\n        RequestMappingHandlerMapping handlerMapping = resolveHandlerMapping(request);\n        if (handlerMapping == null) {\n            throw new NacosRuntimeException(NacosException.SERVER_ERROR,\n                \"Spring MVC RequestMappingHandlerMapping is unavailable\");\n        }\n        boolean parsedRequestPath = false;\n        try {\n            if (handlerMapping.usesPathPatterns()\n                && !ServletRequestPathUtils.hasParsedRequestPath(request)) {\n                ServletRequestPathUtils.parseAndCache(request);\n                parsedRequestPath = true;\n            }\n            HandlerExecutionChain handler = handlerMapping.getHandler(request);\n            if (handler == null || !(handler.getHandler() instanceof HandlerMethod)) {\n                return null;\n            }\n            return ((HandlerMethod) handler.getHandler()).getMethod();\n        } catch (Exception e) {\n            throw new NacosRuntimeException(NacosException.SERVER_ERROR,\n                \"Failed to resolve Spring MVC controller method\", e);\n        } finally {","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/core/src/main/java/com/alibaba/nacos/core/code/ControllerMethodsCache.java#L108-L144","documentation":"Thrown inside ControllerMethodsCache.getMethodFromHandlerMapping when neither the web application context (servlet context) nor the injected ObjectProvider<RequestMappingHandlerMapping> can supply a RequestMappingHandlerMapping bean. This bean is the core Spring MVC component that resolves @RequestMapping handlers, so its absence means the request cannot be dispatched/matched for authorization purposes. It surfaces as a 500 NacosRuntimeException.","triggerScenarios":"Occurs when the Spring WebApplicationContext attached to the request is null, when it lacks the 'requestMappingHandlerMapping' bean, AND the handlerMappingProvider has no unique candidate. Typically seen in embedded/custom servlet configurations, unit/integration tests that mock the servlet context, or a broken/fragmented Spring context where MVC autoconfiguration did not run.","commonSituations":"Running Nacos filter chains outside a fully-bootstrapped Spring MVC stack; a test harness that injects a mock HttpServletRequest without a real ServletContext/ApplicationContext; upgrading Spring Boot where the RequestMappingHandlerMapping bean name changed; a custom context that disables WebMvcAutoConfiguration.","solutions":["Ensure the Nacos server boots through the standard Spring Boot web autoconfiguration so the 'requestMappingHandlerMapping' bean is created.","If testing, attach a real WebApplicationContext to the mock servlet context (MockMvc / WebApplicationContextUtils.setupRequestContext) before invoking the filter.","Verify no custom @EnableWebMvc or excluded autoconfiguration removed the handler mapping bean.","As a temporary workaround, force the legacy resolver with -Dnacos.core.controller.legacy-resolver-enabled=true (deprecated, removed in 3.4.0)."],"exampleFix":"// before: mock request without app context\nMockHttpServletRequest req = new MockHttpServletRequest(\"GET\", \"/v3/admin/ns/service\");\n\n// after: bind the web app context so the handler mapping bean is resolvable\nWebApplicationContextUtils.setupRequestContext(\n    (WebApplicationContext) springContext,\n    mockServletContext, req, null);","handlingStrategy":"validation","validationCode":"RequestMappingHandlerMapping mapping = webApplicationContext != null\n    && webApplicationContext.containsBean(\"requestMappingHandlerMapping\")\n    ? webApplicationContext.getBean(\"requestMappingHandlerMapping\", RequestMappingHandlerMapping.class)\n    : handlerMappingProvider.getIfUnique();\nif (mapping == null) {\n    // do not proceed; the MVC stack is not initialized\n}","typeGuard":null,"tryCatchPattern":"try {\n    Method m = controllerMethodsCache.getMethod(request);\n} catch (NacosRuntimeException e) {\n    if (e.getErrCode() == NacosException.SERVER_ERROR\n        && e.getMessage().contains(\"RequestMappingHandlerMapping is unavailable\")) {\n        // infra misconfiguration — fail fast with a clear 503\n    }\n}","preventionTips":["Boot Nacos through standard Spring Boot web autoconfiguration.","In tests, bind a real WebApplicationContext to the request context.","Do not disable WebMvcAutoConfiguration on a Nacos server node."],"tags":["spring-mvc","controller","infra","handler-mapping","server-error"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}