Skip to content

docs: warn that predefined errors are no longer *HTTPError in v5 - #3063

Merged
aldas merged 1 commit into
labstack:masterfrom
ahashim:docs/v5-error-handler-migration-trap
Aug 1, 2026
Merged

docs: warn that predefined errors are no longer *HTTPError in v5#3063
aldas merged 1 commit into
labstack:masterfrom
ahashim:docs/v5-error-handler-migration-trap

Conversation

@ahashim

@ahashim ahashim commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

API_CHANGES_V5.md documents the new HTTPError shape and the swapped HTTPErrorHandler signature, 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:

if he, ok := err.(*echo.HTTPError); ok {
    code = he.Code
} else {
    code = http.StatusInternalServerError
}

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.Message the 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 at echo.StatusCode(err).

If you'd take a code change as well, httpError could implement As(any) bool so that errors.As(err, &he) matches again. I can send that separately if there's interest.

@ahashim
ahashim force-pushed the docs/v5-error-handler-migration-trap branch from bf27dd4 to 77fd9ad Compare August 1, 2026 14:59
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
ahashim force-pushed the docs/v5-error-handler-migration-trap branch from 77fd9ad to 5024b6a Compare August 1, 2026 15:01
@codecov

codecov Bot commented Aug 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.37%. Comparing base (dcb05f0) to head (5024b6a).
⚠️ Report is 7 commits behind head on master.

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@aldas
aldas merged commit a0a3b53 into labstack:master Aug 1, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants