iflytek/astron-agent · warning · NoHandlerFoundException

NOT_FOUND

NOT_FOUND

Error message

Handler not found exception: {}

What it means

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.

Solutions

1. Verify the full request URL against the controller's mapping, including context-path (server.servlet.context-path) and any gateway prefixes.
2. Check for typos or trailing/missing path segments and path variables in the URL.
3. Confirm the controller class is in a package covered by @ComponentScan / @SpringBootApplication scanning.
4. Check for recent renames in API versioning and update the client to the current route.
5. If you hit the wrong service, correct the port/host so the request reaches the service that owns the route.

Example fix

// before
GET http://host:8080/api/v1/agents  // route is /api/v1/agent/list

// after
GET http://host:8080/api/v1/agent/list

// verify the route exists before calling (from generated route list or spec)
const KNOWN_ROUTES = ['/api/v1/agent/list', '/api/v1/agent/create'];
if (!KNOWN_ROUTES.includes(path)) throw new Error(`Unknown route: ${path}`);

const isKnownRoute = (url, routes) => routes.some((r) => url.endsWith(r));

try {
  return await axios.get(url);
} catch (e) {
  if (e.response?.status === 404) {
    console.error(`No handler for ${url}: check path, context-path and API version`);
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

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

• BAD_REQUEST
• METHOD_NOT_ALLOWED
• 20201
• 23900
• 40023

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/d4adb49df1e074e4. Report an issue: GitHub.

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/config/exception/handler/GlobalExceptionHandler.java:109

        log.warn("HTTP message not readable exception: {}", e.getMessage(), e);
        return ApiResult.error(ResponseEnum.BAD_REQUEST.getCode(), "parameter.illegal");
    }

    /** Handle HTTP request method not supported exceptions */
    @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
    @ResponseStatus(HttpStatus.METHOD_NOT_ALLOWED)
    public ApiResult<Void> handleHttpRequestMethodNotSupportedException(HttpRequestMethodNotSupportedException e) {
        String messageCode = "http.method.not.supported";
        log.warn("HTTP request method not supported exception: {}", messageCode, e);
        return ApiResult.error(ResponseEnum.METHOD_NOT_ALLOWED.getCode(), messageCode);
    }

    /** Handle handler not found exceptions */
    @ExceptionHandler(NoHandlerFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiResult<Void> handleNoHandlerFoundException(NoHandlerFoundException e) {
        String messageCode = "http.url.not.found";
        log.warn("Handler not found exception: {}", messageCode, e);
        return ApiResult.error(ResponseEnum.NOT_FOUND.getCode(), messageCode);
    }

    /** Handle other exceptions */
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ApiResult<Void> handleException(Exception e) {
        log.error("Unknown exception: {}", e.getMessage(), e);
        return ApiResult.error(ResponseEnum.SYSTEM_ERROR.getCode(), "error.system");
    }

}

View on GitHub (pinned to 5e758547a8)