Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

FallbackMiddleware condition can't inspect the request

Open Beginner friendly
  • Is something wrong?
#5,829 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
85/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
dart
Domain
backend

Research direction

Locate the FallbackMiddleware implementation in the Serverpod Dart codebase, add the new optional when callback that receives both the incoming Request and outgoing Response (retaining the existing on parameter for backwards compatibility), implement a robust acceptsHtml helper that correctly parses the Accept header per HTTP spec (handling case insensitivity, q=0 values and malformed input without errors), then add unit tests verifying the new request-aware fallback logic and the helper's edge case behavior.

Written by the indexing model from the issue text.

Description

area: web server enhancement
Problem to Solve

FallbackMiddleware decides whether to use the fallback from the response alone (on: bool Function(Response)). It can't see the request, so it can't tell a browser loading a page apart from a missing image, an API call or a client that asked for JSON or markdown.

As a result, it can't be used for one of the most common fallback cases: a custom HTML 404 page. Either every 404 gets an HTML body, assets and API responses included, or you write your own middleware. fallbackRoute isn't an alternative when a StaticRoute.directory is mounted at the root, because its /** path matches every request (#4343).

Proposal

Let the condition inspect the request as well as the response. To stay backwards compatible, this could be a new optional parameter next to on:

FallbackMiddleware(
  fallback: notFoundPageRoute,
  when: (request, response) =>
      response.statusCode == 404 && request.acceptsHtml,
)

A helper for "accepts text/html" would also help. It's easy to get wrong: media types are case-insensitive, q=0 means "not acceptable", and a malformed Accept header shouldn't throw.

Use Case

A website serves static files from the root and wants a branded 404 page. Browsers requesting an unknown page (GET/HEAD with Accept: text/html) should get the HTML page with status 404. Missing assets, API calls and non-HTML clients should keep a plain 404.

Alternatives
  • Write a custom middleware that duplicates FallbackMiddleware and adds a request check. This works, but every app needs it.
  • Mount static files under a prefix so fallbackRoute can fire. This changes every asset URL.
Additional context

No response

How experienced are you with this library?

Expert - Experienced and comfortable with using this library in complex projects

Are you interested in working on a PR for this?
  • I want to work on this
Dominant language
Dart
Stars
3.3k
Forks
382
Avg merge
1d 3h
Merged PRs (30d)
62

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from serverpod/serverpod

All issues in serverpod/serverpod

Similar issues

More Dart issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.