Inconsistent behavior of /** syntax in TrieRouter vs other routers

[NiebieskiRekin]

What is the feature you are proposing?

Description

While /** is not explicitly documented as standard Hono syntax, it appears to be supported (or treated equivalently to /*) by RegExpRouter, PatternRouter, and LinearRouter.

However, TrieRouter (which SmartRouter defaults to in many cases) fails to match routes defined with /**, returning a 404. This creates a hidden pitfall where switching routers (or adding routes that cause SmartRouter to switch internal strategies) breaks existing route matching.

Code sample

The following code demonstrates that TrieRouter returns 404 for /auth/**, but changing the router to another one or the route to /* makes it work.

import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { getRouterName, showRoutes } from 'hono/dev';
import { PatternRouter } from 'hono/router/pattern-router';
import { LinearRouter } from 'hono/router/linear-router';
import { RegExpRouter } from 'hono/router/reg-exp-router';
import { TrieRouter } from 'hono/router/trie-router';

const app = new Hono({router: new TrieRouter()})
  .on(["POST", "GET"], "/auth/**", (c) => c.json({})) // Note **

showRoutes(app)

serve({
  fetch: app.fetch,
  port: 3001
}, (info) => {
  console.log(getRouterName(app));
  fetch(`http://localhost:${info.port}/auth/hello`).then(async (res)=>{
    if (res.ok){
      console.log("OK!")
    } else {
      console.error("Error! "+res.status)
    }
  }
  )
})

Output:

POST  /auth/**
GET   /auth/**
TrieRouter
Error! 404

After changing routers:

RegExpRouter

const app = new Hono({router: new RegExpRouter()})
  .on(["POST", "GET"], "/auth/**", (c) => c.json({}))

Output:

POST  /auth/**
GET   /auth/**
RegExpRouter
OK!

PatternRouter

const app = new Hono({router: new PatternRouter()})
  .on(["POST", "GET"], "/auth/**", (c) => c.json({}))

Output:

POST  /auth/**
GET   /auth/**
PatternRouter
OK!

LinearRouter

const app = new Hono({router: new LinearRouter()})
  .on(["POST", "GET"], "/auth/**", (c) => c.json({}))

Output:

POST  /auth/**
GET   /auth/**
LinearRouter
OK!

After changing the route to /*

const app = new Hono({router: new TrieRouter()})
  .on(["POST", "GET"], "/auth/*", (c) => c.json({})) // Note *

Output:

POST  /auth/*
GET   /auth/*
TrieRouter
OK!

Proposal

Behavior should be consistent across routers.

If /** is intended to be supported as an alias for /* (or a recursive wildcard), TrieRouter should support it.

If /** is invalid syntax, other routers should ideally not match it, or Hono should warn during route registration or in the docs.

Currently, it works in 3 out of 4 routers.

TrieRouter:    404 Not Found
RegExpRouter:  200 OK
PatternRouter: 200 OK
LinearRouter:  200 OK

[usualoma]

Hi @NiebieskiRekin, thanks for pointing that out.

Considering patterns like /auth/**/path and other combinations, I believe it's appropriate to mark paths containing ** (or *****, etc.) as invalid. TrieRouter's behavior is correct.

However, currently, Hono has almost no implementation for "invalid (or unsupported) path checking functionality." Once we start, I think there will be other "invalid conditions that should be checked."

While "router compatibility" is certainly desirable, whether it's worth adding code (increasing both maintenance costs and bundle size) to ensure consistent behavior for invalid (or unsupported) paths is a bit of a gray area.

[kasharkzy]

Hi @usualoma, I dug into the source to understand the root cause better.

In TrieRouter, getPattern('**') in src/utils/url.ts returns null, so ** is stored as a literal node key. During search(), only '*' is checked as a wildcard segment, meaning routes registered with /** silently return 404.

In RegExpRouter, /** coincidentally works because trie.ts tokenizes ** as two separate * characters since the last * is the final token, it triggers ONLY_WILDCARD_REG_EXP_STR. The behavior is accidental rather than intentional.

Given your position that /** is invalid syntax, here are two concrete implementation approaches:

Option A Centralized validation in HonoBase
Add a path check in HonoBase.#addRoute() that throws when a segment containing ** is detected. Single enforcement point, works regardless of which router is active, and keeps the validation clearly separated from routing logic.

Option B Per-router rejection via UnsupportedPathError
Each router's add() throws when it encounters **. SmartRouter already handles UnsupportedPathError to decide which router to use, so this would need careful handling to avoid treating an invalid path as "unsupported by this router, try the next one."

Option A feels cleaner since it avoids polluting SmartRouter's fallback logic. Happy to open a PR for whichever direction you prefer or just looking to validate the approach before starting.

[usualoma]

Hi @kasharkzy,
Thank you for your input.

We understand the implementation details, but we haven’t yet settled on a specification that strikes the right balance. Since performance and code size are critical across all routers, we’d prefer to avoid adding any additional code if possible.

Would it be okay if we discussed this further within the development team?

Also, if you have any specific examples of issues you’re facing in practice, we’d appreciate it if you could share them with us.

[NiebieskiRekin]

Hi, sorry for the delay in my response. Seeing some of these responses I decided that it might help if I share some more context why I created this issue.

When I was just starting out with Hono I made a false assumption that /** would act similarly to shell globbing. It seemingly worked just fine for quite a long time, but then suddenly my authentication middleware started returning 404 after changing an unrelated CRUD endpoint. It took me a while to debug, but after reaching a certain number of endpoints/route complexity Hono automatically switched to a different router implementation that handles this undefined /** differently.

Having different routers with some paths giving undefined behavior is totally fine for performance reasons. Having a warning made by the Typescript compiler or Eslint would have been very helpful. If the maintenance burden of having these checks at development stages is not worth it then a section in the docs specifying that /* is sufficent for matching all subpaths and what are the potential quirks of wildcard matching will be excellent

[usualoma]

Hi @NiebieskiRekin,
Thank you for your response.
That difference in behavior is surprising and not ideal.

Even if we don't have to go to the trouble of making all routers behave exactly the same, I think it would be better to avoid confusion regarding that section ( /** ) for RegExpRouter and TrieRouter, which are used by default and switch behavior without explicit user intervention. If we're looking for the smallest possible change, it might be worth having RegExpRouter return an UnsupportedPathError for /**.

There’s also the issue of documentation, but documentation is fundamentally meant to explain “supported formats” in detail, not “unsupported formats,” so it’s debatable whether it’s appropriate to explicitly include /**. Furthermore, we don’t want to build a framework that requires users to read the documentation before using it. (Although these days, if we write it down, AI might read it for us.)

If we were to solve this using type checking (without runtime checks), there’s an approach like the one below, but it feels like it adds a bit too much code.
#4923