docs: warn that predefined errors are no longer *HTTPError in v5 - #3063
Merged
aldas merged 1 commit intoAug 1, 2026
Merged
Conversation
ahashim
force-pushed
the
docs/v5-error-handler-migration-trap
branch
from
August 1, 2026 14:59
bf27dd4 to
77fd9ad
Compare
A v4-style custom HTTPErrorHandler that type-asserts err.(*echo.HTTPError) silently stops matching the router's predefined errors (echo.ErrNotFound, echo.ErrMethodNotAllowed, ...) in v5, because they are now immutable sentinels implementing only HTTPStatusCoder. The result is every unmatched route being rendered as a 500 instead of a 404, with no compile-time or runtime signal. Document the trap in the HTTPError section and the migration guide's error handler step, pointing at echo.StatusCode(err) as the correct replacement.
ahashim
force-pushed
the
docs/v5-error-handler-migration-trap
branch
from
August 1, 2026 15:01
77fd9ad to
5024b6a
Compare
aldas
approved these changes
Aug 1, 2026
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3063 +/- ##
==========================================
+ Coverage 93.34% 93.37% +0.02%
==========================================
Files 43 44 +1
Lines 4735 4783 +48
==========================================
+ Hits 4420 4466 +46
- Misses 192 193 +1
- Partials 123 124 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
API_CHANGES_V5.mddocuments the newHTTPErrorshape and the swappedHTTPErrorHandlersignature, but not that the predefined errors (echo.ErrNotFound,echo.ErrMethodNotAllowed, ...) are no longer*echo.HTTPError.That gap bit us in production after migrating an app to v5.3.1. A common v4 custom error handler does:
In v5 the router returns unexported sentinels that only implement
HTTPStatusCoder, so the assertion never matches and every unmatched route renders as a 500 instead of a 404. Nothing fails at compile time or at runtime. We only noticed because scanner traffic showed up in our logs as thousands of 500s.The sentinel design looks intentional, since it prevents globally mutating
echo.ErrNotFound.Messagethe way v4 allowed, so this PR only adds documentation: a warning in the "HTTPError Simplified" section and a short note in migration step 4, both pointing atecho.StatusCode(err).If you'd take a code change as well,
httpErrorcould implementAs(any) boolso thaterrors.As(err, &he)matches again. I can send that separately if there's interest.