Type inference: wrong error location when handler return type is invalid — error points to route path string

[danielo515]

Summary

When defining a route, if the handler returns an invalid type (i.e., something not compatible with the expected Response/Promise<Response> or helper return types like c.text/c.json), TypeScript reports a type error on the route path string (second argument) rather than on the handler/callback. This makes it hard to locate the actual problem and feels like an overload inference/diagnostic issue.

Minimal repro (TypeScript)

import { Hono } from 'hono'

const app = new Hono()

// The handler is intentionally incorrect
  app.on(["GET", "POST"], "/test/*", () => {
    return 123;
  });

export default app

In projects (and in my local setup), the compilation/typecheck error points at the string "/test" (second argument) complaining about incompatibility with the expected overload, rather than highlighting the handler’s return type issue in the second argument. The callback is the root cause, but the path string is flagged.

Expected behavior

• TypeScript diagnostics should point to the handler/callback (last argument), specifically the invalid return type, so it’s clear what to fix.

Actual behavior

• The error is attached to the path string literal, with a message indicating the call does not match any overload, which obscures that the handler return type is the real issue.

Why this matters

• Misleading diagnostics slow down debugging. When the path string is highlighted, it suggests a route/path mismatch instead of a handler type issue. This is especially confusing for newer users.

Environment

• Hono: latest 4.7.8
• TypeScript: 5.8.x
• Node.js: 22.x

Workaround

• Manually inspect the handler return type when a route call reports overload mismatch on the path.

Request

• Improve type definitions/overloads so that invalid handler return types produce diagnostics on the handler/callback rather than the path string. Even a clearer error message directing attention to the callback would help.

Thanks for your great work on Hono! 🙏

[yusukebe]

Hi @danielo515

I tried to enable it, but I remember it's super hard or impossible due to TypeScript limitations, and I gave up. The type definitions around handlers are extremely complex! It's our challenge to improve the type things.

[danielo515]

Yeah, I can understand that. Thanks for all the effort you put into it anyway.

Cheers

On Fri, Aug 8, 2025 at 10:25 PM Yusuke Wada @.***> wrote:

yusukebe left a comment (honojs/hono#4345) https://github.com/honojs/hono/issues/4345#issuecomment-3169204770

Hi @danielo515 https://github.com/danielo515

I tried to enable it, but I remember it's super hard or impossible due to TypeScript limitations, and I gave up. The type definitions around handlers are extremely complex! It's our challenge to improve the type things.

— Reply to this email directly, view it on GitHub https://github.com/honojs/hono/issues/4345#issuecomment-3169204770, or unsubscribe https://github.com/notifications/unsubscribe-auth/AARKJWI56L7LKGZYQWADWGL3MUBU5AVCNFSM6AAAAACDM5VMRCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCNRZGIYDINZXGA . You are receiving this because you were mentioned.Message ID: @.***>

--

https://danielorodriguez.com

[yusukebe]

So, I added an enhancement label to this issue. Hoping we can do it.