[fix] ctx.assert() throws specific error classes #1925

Activity

1. isjs-d

   added

   bug

   on Jan 25, 2026
2. isjs-d commented on Jan 25, 2026

   

   isjs-d

   on Jan 25, 2026

   Author

   More actions

   Update: This is likely an issue with http-assert, which uses: "http-errors": "~1.8.0"
   while Koa uses: "http-errors": "^2.0.0"

   👀React with 👀1Reacted by Jeff Wainwright
3. Jerry-CodeHub commented on Jan 29, 2026

   

   Jerry-CodeHub

   on Jan 29, 2026

   Contributor

   More actions

   Reason
   This issue involves the problem of cross-module instance checks with instanceof in JavaScript and the complexity of Koa's dependency chain.

   Dependency chain:
   Koa
   ├── ctx.throw() → Use http-errors directly
   ├── ctx.assert() → Use http-assert → Indirectly use http-errors
   └── Export HttpError → From http-errors

   Question:

   1. http-errors creates specific error subclasses: When calling createError(401, 'Unauthorized'), what is actually returned is an instance of the UnauthorizedError class, not the HttpError class itself.
   2. Multiple instance issue: If http-assert and koa each depend on different versions of http-errors, then their HttpError base classes are actually different constructor instances, causing instanceof checks to fail.
   3. npm dependency resolution: In npm/yarn/pnpm, if the version ranges are different, multiple copies of http-errors may be installed:

   node_modules/
   ├── http-errors/ # The version of koa's dependency
   └── http-assert/
   └── node_modules/
   └── http-errors/ # Different versions of http-assert dependencies

   Verification:

   import { HttpError } from 'koa'
   import createError from 'http-errors'
   
   // ctx.throw() The behavior of...
   const throwError = createError(401, 'Unauthorized')
   console.log(throwError instanceof HttpError)        // ✅ true (from the same http-errors)
   console.log(throwError instanceof createError.HttpError) // ✅ true
   console.log(throwError.constructor.name)            // 'UnauthorizedError'
   
   // The behavior of ctx.assert() - different versions of http-errors may be used
   // If the versions are inconsistent, the instanceof check will fail

   Solution:

   Use createError.isHttpError() for checking (recommended)

   The http-errors module provides the isHttpError() function, which uses duck typing and does not rely on instanceof:

   import createError from 'http-errors'
   
   app.use(async (ctx, next) => {
     try {
       await next()
     } catch (err) {
       // ✅ Recommendation: Use isHttpError for the check.
       if (createError.isHttpError(err)) {
         ctx.status = err.status
         ctx.body = { message: err.message }
       } else {
         ctx.status = 500
         ctx.body = { message: 'Internal Server Error' }
         ctx.app.emit('error', err, ctx)
       }
     }
   })

   The internal implementation of isHttpError() is based on duck typing:

   // The implementation logic of the isHttpError method in http-errors
   function isHttpError(val) {
     if (!val || typeof val !== 'object') return false
     
     // Check if it is an instance of HttpError
     if (val instanceof HttpError) return true
     
     // Duck type checking
     return typeof val.status === 'number' &&
            typeof val.statusCode === 'number' &&
            typeof val.expose === 'boolean'
   }
4. mibragimov

   added a commit that references this issue on Mar 7, 2026

   fix: ctx.assert() now throws errors instanceof HttpError

   ...

   This issue will close once commit 943b7d2 is merged into the 'master' branch.

   943b7d2
5. guoyangzhen

   added a commit that references this issue on Mar 18, 2026

   fix: ctx.assert() throws HttpError instances

   ...

   This issue will close once commit 6f653d2 is merged into the 'master' branch.

   6f653d2
6. yowainwright

   closed this as completedin #1998on Sep 2, 2026
7. pull

   added a commit that references this issue on Sep 2, 2026

   patch: make ctx.assert errors instanceof HttpError (koajs#1998)

   ...

   This issue will close once commit 1061776 is merged into the 'master' branch.

   1061776