{"record":{"id":"d4adb49df1e074e4","repo":"iflytek/astron-agent","slug":"not-found","errorCode":"NOT_FOUND","errorMessage":"Handler not found exception: {}","messagePattern":"Handler not found exception: (.+?)","errorType":"http","errorClass":"NoHandlerFoundException","httpStatus":404,"severity":"warning","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/config/exception/handler/GlobalExceptionHandler.java","lineNumber":109,"sourceCode":"        log.warn(\"HTTP message not readable exception: {}\", e.getMessage(), e);\n        return ApiResult.error(ResponseEnum.BAD_REQUEST.getCode(), \"parameter.illegal\");\n    }\n\n    /** Handle HTTP request method not supported exceptions */\n    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)\n    @ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)\n    public ApiResult<Void> handleHttpRequestMethodNotSupportedException(HttpRequestMethodNotSupportedException e) {\n        String messageCode = \"http.method.not.supported\";\n        log.warn(\"HTTP request method not supported exception: {}\", messageCode, e);\n        return ApiResult.error(ResponseEnum.METHOD_NOT_ALLOWED.getCode(), messageCode);\n    }\n\n    /** Handle handler not found exceptions */\n    @ExceptionHandler(NoHandlerFoundException.class)\n    @ResponseStatus(HttpStatus.NOT_FOUND)\n    public ApiResult<Void> handleNoHandlerFoundException(NoHandlerFoundException e) {\n        String messageCode = \"http.url.not.found\";\n        log.warn(\"Handler not found exception: {}\", messageCode, e);\n        return ApiResult.error(ResponseEnum.NOT_FOUND.getCode(), messageCode);\n    }\n\n    /** Handle other exceptions */\n    @ExceptionHandler(Exception.class)\n    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)\n    public ApiResult<Void> handleException(Exception e) {\n        log.error(\"Unknown exception: {}\", e.getMessage(), e);\n        return ApiResult.error(ResponseEnum.SYSTEM_ERROR.getCode(), \"error.system\");\n    }\n\n}\n","sourceCodeStart":91,"sourceCodeEnd":122,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/config/exception/handler/GlobalExceptionHandler.java#L91-L122","documentation":"Spring MVC throws NoHandlerFoundException when no controller mapping matches the request URL (dispatcher finds no handler). The handler returns HTTP 404 NOT_FOUND with message code 'http.url.not.found'. Note this only fires when throw-exception-if-no-handler-found is enabled; otherwise the container's default 404 page appears.","triggerScenarios":"Requesting a path with no @RequestMapping match: typo in URL, wrong context path/base URL, missing path variable segment, or calling a controller that isn't component-scanned.","commonSituations":"Frontend calls an endpoint that was renamed or removed in a new backend version; gateway prefix stripping misconfigured; wrong service port (hitting toolkit instead of hub); servlet context-path not included/excluded correctly.","solutions":["Verify the full request URL against the controller's mapping, including context-path (server.servlet.context-path) and any gateway prefixes.","Check for typos or trailing/missing path segments and path variables in the URL.","Confirm the controller class is in a package covered by @ComponentScan / @SpringBootApplication scanning.","Check for recent renames in API versioning and update the client to the current route.","If you hit the wrong service, correct the port/host so the request reaches the service that owns the route."],"exampleFix":"// before\nGET http://host:8080/api/v1/agents  // route is /api/v1/agent/list\n\n// after\nGET http://host:8080/api/v1/agent/list","handlingStrategy":"validation","validationCode":"// verify the route exists before calling (from generated route list or spec)\nconst KNOWN_ROUTES = ['/api/v1/agent/list', '/api/v1/agent/create'];\nif (!KNOWN_ROUTES.includes(path)) throw new Error(`Unknown route: ${path}`);","typeGuard":"const isKnownRoute = (url, routes) => routes.some((r) => url.endsWith(r));","tryCatchPattern":"try {\n  return await axios.get(url);\n} catch (e) {\n  if (e.response?.status === 404) {\n    console.error(`No handler for ${url}: check path, context-path and API version`);\n  } else throw e;\n}","preventionTips":["Generate the frontend client from the backend OpenAPI spec instead of hand-writing URLs.","Include server.servlet.context-path and gateway prefixes consistently in the base URL.","Track route renames via API versioning and deprecate old paths.","Smoke-test all routes after backend version upgrades."],"tags":["http","spring-mvc","not-found","routing"],"backgroundTag":"resource-not-found","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}