Return `405 Method Not Allowed` when a path exists but the HTTP method is unsupported

[silvioprog]

What is the feature you are proposing?

Add a built-in, global handler such as app.methodNotAllowed() that is triggered when a path matches an existing route but the HTTP method is not supported. This handler would return 405 Method Not Allowed and optionally include an Allow header listing the permitted methods.

This should be an opt-in feature, so Hono keeps its current behavior by default, but allows projects that want stricter HTTP semantics to enable proper 405 handling.

Problem

Currently, when a request is made to a path that exists but the HTTP method is not supported, Hono returns 404 Not Found. From an HTTP semantics perspective, this is misleading: the resource exists, but the method is not allowed. The correct response in this case should be 405 Method Not Allowed.

This behavior makes it harder for API clients and developers to distinguish between:

• A route that truly does not exist (404)
• A route that exists but does not support the given method (405)

Also, the preferred behavior can vary by project. Some APIs want strict HTTP compliance and expect 405, while others prefer returning 404 for security reasons. Hono should not enforce one approach globally.

Expected Behavior

When app.methodNotAllowed() is configured and a path is registered but the requested HTTP method is not supported, Hono should:

1. Return 405 Method Not Allowed
2. Include an Allow header listing the supported methods for that path

This follows the HTTP specification and matches the behavior of many other web frameworks.

Example

app.get('/hello', (c) => c.text('Hello'))

A POST /hello request should return:

405 Method Not Allowed
Allow: GET

instead of:

404 Not Found

Benefits

• Keeps Hono’s current secure default behavior
• Allows projects to opt into proper HTTP semantics
• Better alignment with HTTP standards
• Clearer API semantics for consumers
• Easier debugging and client-side error handling
• More predictable behavior for developers building RESTful APIs with Hono

[usualoma]

Hi @silvioprog, thank you for your proposal.

I understand what you want to achieve, but since Hono does not distinguish between middleware and handlers, the approach in your pull request will not work as expected in general applications. Even if we switched to another approach, implementing this functionality would likely be difficult.

It seems unnecessary to me to change Hono's design just to implement a feature that returns a "405 Method Not Allowed" response.

[silvioprog]

Hey @usualoma, thanks a lot for taking the time to reply, I really appreciate it.

I understand the concern about Hono not distinguishing between middleware and handlers, and that this makes a generic solution harder. My intention with this proposal is not to change Hono's default behavior or its core design, but to offer an opt-in mechanism for projects that want stricter HTTP semantics.

Right now, the main issue for me is that there is no way to globally distinguish:

• this path does not exist (404)
• this path exists but the method is not allowed (405)

without adding .all() handlers or custom logic to every route, which does not scale well for larger APIs.

When you say the approach in the PR would not work as expected in general applications, could you clarify in which scenarios it breaks or becomes ambiguous? Understanding those concrete cases would help me see whether the proposal is fundamentally flawed or if there is an alternative design that fits Hono better.

Also, I'm not suggesting Hono must return 405. The idea is precisely to keep the current behavior as the secure default, while allowing projects that care about HTTP compliance (REST APIs, OpenAPI-based clients, etc.) to explicitly enable this behavior.

Even if a built-in app.methodNotAllowed() hook is not viable, do you think:

• a router-level option
• or a documented official pattern
• or exposing enough internal information to implement this cleanly in userland

would be acceptable?

My main goal here is not specifically "405 for the sake of 405", but having a scalable and explicit way to differentiate "route missing" vs "method not supported" without per-route workarounds.

[usualoma]

@silvioprog, thank you for the reply!

When you say the approach in the PR would not work as expected in general applications, could you clarify in which scenarios it breaks or becomes ambiguous? Understanding those concrete cases would help me see whether the proposal is fundamentally flawed or if there is an alternative design that fits Hono better.

If you add even one middleware using app.use(), the implementation in #4637 will no longer call methodNotAllowed. You might think, "If someone wants to use methodNotAllowed, they just shouldn't use app.use()," but since app.use() is a core feature of Hono, we don't consider it appropriate to include functionality that cannot be used alongside it.

const app = new Hono()

app.methodNotAllowed((c, allowedMethods) => {
  return c.text(`Method not allowed. Allowed: ${allowedMethods.join(', ')}`, 405, {
    Allow: allowedMethods.join(', ').toUpperCase(),
  })
})

// If you add even one piece of middleware in app.use, methodNotAllowed will never be called
app.use(poweredBy())

app.get('/', (c) => {
  return new Response('Hello, World!')
})

While there are several ways to solve this in userland, I believe implementing it in middleware, as shown below, offers relatively high versatility. If middleware could receive the app (or information equivalent to app.routes), we could make it more versatile. However, since we cannot obtain such information, this is how it is currently implemented.

let methodNotAllowedRouter: TrieRouter<string[]> | undefined;
app.use(async (c, next) => {
  await next()

  if (c.res.status === 404) {
    if (!methodNotAllowedRouter) {
      const paths = new Map<string, string[]>()
      for (const route of app.routes) {
        if (route.method === METHOD_NAME_ALL) {
          // Skip adding middleware
          continue
        }
        const methods = paths.get(route.path) || []
        methods.push(route.method.toUpperCase())
        paths.set(route.path, methods)
      }
      methodNotAllowedRouter = new TrieRouter()
      for (const [path, methods] of paths) {
        methodNotAllowedRouter.add(METHOD_NAME_ALL, path, methods)
      }
    }

    const methods = methodNotAllowedRouter.match(METHOD_NAME_ALL, c.req.path)[0].reduce<string[]>((acc, [route]) => {
      return acc.concat(route)
    }, []).filter((method) => method !== c.req.method.toUpperCase())

    if (methods.length > 0) {
      return new Response('Method Not Allowed', {
        status: 405,
        headers: {
          Allow: methods.join(', '),
        },
      })
    }
  }
})

[silvioprog]

Hi @usualoma, thank you again for the detailed explanation, that was really helpful, and I completely agree that anything considered "core" must work correctly with app.use(), since middleware is fundamental in Hono.

I've just updated the PR so that methodNotAllowed now works even when app.use() is used, addressing the issue you pointed out.

After your example, I also agree that a middleware-based solution is probably the right direction. It avoids growing Hono's core bundle and keeps the framework minimal while still allowing projects to opt into stricter HTTP semantics.

I tried to adapt your middleware example locally, but I still couldn't get it to return 405 in my tests. This is roughly what I tested:

import { Hono } from 'hono'
import { poweredBy } from 'hono/powered-by'
import { PatternRouter } from 'hono/router/pattern-router'

const app = new Hono()

app.use(poweredBy())

app.get('/', (c) => c.text('Hello'))

let methodNotAllowedRouter: PatternRouter<string[]> | undefined

app.use(async (c, next) => {
  await next()

  if (c.res.status === 404) {
    if (!methodNotAllowedRouter) {
      const paths = new Map<string, string[]>()
      for (const route of app.routes) {
        if (route.method === 'ALL') {
          // Skip adding middleware
          continue
        }
        const methods = paths.get(route.path) || []
        methods.push(route.method.toUpperCase())
        paths.set(route.path, methods)
      }
      methodNotAllowedRouter = new PatternRouter()
      for (const [path, methods] of paths) {
        methodNotAllowedRouter.add('ALL', path, methods)
      }
    }

    const methods = methodNotAllowedRouter
      .match('ALL', c.req.path)[0]
      .reduce<string[]>((acc, [route]) => {
        return acc.concat(route)
      }, [])
      .filter((method) => method !== c.req.method.toUpperCase())

    if (methods.length > 0) {
      return new Response('Method Not Allowed', {
        status: 405,
        headers: {
          Allow: methods.join(', '),
        },
      })
    }
  }
})

export default app

But in my local test, a POST / is still returning 404 instead of 405:

% curl 'http://localhost:3000/'
Hello
% curl -X POST 'http://localhost:3000/'
404 Not Found

I'm likely missing something subtle in how the router is built or how matching is performed, so I'll keep digging. I'll also look into moving the router construction outside the middleware so it isn't created lazily and can behave more predictably

Conceptually, I'm fully aligned with you: middleware is the right abstraction for this, not a new core API. My only concern is that without access to routing metadata, this pattern becomes quite hard and fragile to implement correctly in userland.

I'm also totally open to using a built-in router instance directly, something like:

const router = new PatternRouter()

// use "router" here instead of "app.get", "app.post" etc.

const app = new Hono({ router })

app.use(async (c, next) => {
  // use `router` here to detect:
  // - path exists
  // - method is not allowed
})

or any equivalent pattern that allows middleware to query the same routing information Hono already has internally.

That feels like a very clean compromise:

• no change to Hono's default behavior
• no increase in the core bundle size
• still fully opt-in
• and enough power in userland to implement proper 405 handling reliably

Since #4637 is specifically about adding a core app.methodNotAllowed() API, if the preferred approach is middleware/userland, I'm happy to close or leave the PR as-is and instead open a separate PR that adds an official middleware implementation + documentation.

[usualoma]

@silvioprog

Thanks for checking. My example was incorrect. To change a 404 that had already been set, simply returning the Response object wasn't enough. You can resolve it by doing the following:

(Also, this middleware must be registered before each handler)

import { Hono } from "hono";
import { HTTPException } from 'hono/http-exception'
import { poweredBy } from 'hono/powered-by'
import { METHOD_NAME_ALL } from 'hono/router'
import { TrieRouter } from 'hono/router/trie-router'

const app = new Hono()

let methodNotAllowedRouter: TrieRouter<string[]> | undefined;
app.use(async (c, next) => {
  await next()

  if (c.res.status === 404) {
    if (!methodNotAllowedRouter) {
      const paths = new Map<string, string[]>()
      for (const route of app.routes) {
        if (route.method === METHOD_NAME_ALL) {
          // Skip adding middleware
          continue
        }
        const methods = paths.get(route.path) || []
        methods.push(route.method.toUpperCase())
        paths.set(route.path, methods)
      }
      methodNotAllowedRouter = new TrieRouter()
      for (const [path, methods] of paths) {
        methodNotAllowedRouter.add(METHOD_NAME_ALL, path, methods)
      }
    }

    const methods = methodNotAllowedRouter.match(METHOD_NAME_ALL, c.req.path)[0].reduce<string[]>((acc, [route]) => {
      return acc.concat(route)
    }, []).filter((method) => method !== c.req.method.toUpperCase())

    if (methods.length > 0) {
      const res = new Response('Method Not Allowed', {
        status: 405,
        headers: {
          Allow: methods.join(', '),
        },
      })
      throw new HTTPException(405, { res })
    }
  }
})

app.use(poweredBy())

app.get('/', (c) => {
  return new Response('Hello, World!')
})

[usualoma]

While “passing app” feels a bit awkward, it can be encapsulated like typical middleware as follows:

method-not-allowed.ts

import { HTTPException } from 'hono/http-exception'
import { METHOD_NAME_ALL } from 'hono/router'
import { TrieRouter } from 'hono/router/trie-router'
import type { Hono } from "hono"
import type { MiddlewareHandler } from 'hono/types'

export const methodNotAllowed = (app: Hono): MiddlewareHandler => {
  let methodNotAllowedRouter: TrieRouter<string[]> | undefined;
  return async (c, next) => {
    await next()

    if (c.res.status === 404) {
      if (!methodNotAllowedRouter) {
        const paths = new Map<string, string[]>()
        for (const route of app.routes) {
          if (route.method === METHOD_NAME_ALL) {
            // Skip adding middleware
            continue
          }
          const methods = paths.get(route.path) || []
          methods.push(route.method.toUpperCase())
          paths.set(route.path, methods)
        }
        methodNotAllowedRouter = new TrieRouter()
        for (const [path, methods] of paths) {
          methodNotAllowedRouter.add(METHOD_NAME_ALL, path, methods)
        }
      }

      const methods = methodNotAllowedRouter.match(METHOD_NAME_ALL, c.req.path)[0].reduce<string[]>((acc, [route]) => {
        return acc.concat(route)
      }, []).filter((method) => method !== c.req.method.toUpperCase())

      if (methods.length > 0) {
        const res = new Response('Method Not Allowed', {
          status: 405,
          headers: {
            Allow: methods.join(', '),
          },
        })
        throw new HTTPException(405, { res })
      }
    }
  }
}

app.ts

import { Hono } from 'hono'
import { poweredBy } from 'hono/powered-by'
import { methodNotAllowed } from './method-not-allowed'

const app = new Hono()

app.use(methodNotAllowed(app))
app.use(poweredBy())

app.get('/', (c) => {
  return new Response('Hello, World!')
})

export default app

[usualoma]

Hi @yusukebe

Regarding this issue, I don't think we need to make any changes to Hono's core to address it. (If necessary, it might be possible to allow the middleware to access app information without impacting performance, but I don't think that's necessary either.)

Do you have any thoughts?

[yusukebe]

Hi @usualoma

I agree with your opinion. We should not add the code to hono-base.ts and other hono core. But, creating a new middleware to support, like "Method Not Allowed Middleware", seems to be good.

If necessary, it might be possible to allow the middleware to access app information without impacting performance, but I don't think that's necessary either.

It's a rare case that we make middleware access to app. So we don't have to do that.

[gitme1-ym]

[usualoma]

Hi @yusukebe
Thanks for the reply.

Yeah, it is a bit odd that we have to pass the app as an argument, but it might be worth considering adding the
methodNotAllowed from the comment below to Hono's core.

#4633 (comment)

[yusukebe]

@usualoma The methodNotAllowed is a middleware (that receives the app), right?

[usualoma]

@yusukebe

Yes

The methodNotAllowed is a middleware (that receives the app), right?

[yusukebe]

@usualoma

I got it. I also think the methodNotAllowed is worth adding.