diff --git a/docs/Reference/Server.md b/docs/Reference/Server.md
index c0f3b80f422..27fa1294c4e 100644
--- a/docs/Reference/Server.md
+++ b/docs/Reference/Server.md
@@ -1011,6 +1011,9 @@ Note that the array contains the `fastify.server.address()` too.
#### getDefaultRoute
+**Notice**: this method is deprecated and should be removed in the next Fastify
+major version.
+
The `defaultRoute` handler handles requests that do not match any URL specified
by your Fastify application. This defaults to the 404 handler, but can be
overridden with [setDefaultRoute](#setdefaultroute). Method to get the
@@ -1023,15 +1026,19 @@ const defaultRoute = fastify.getDefaultRoute()
#### setDefaultRoute
-**Note**: The default 404 handler, or one set using `setNotFoundHandler`, will
+**Notice**: this method is deprecated and should be removed in the next Fastify
+major version. Please, consider to use `setNotFoundHandler` or a wildcard
+matching route.
+
+The default 404 handler, or one set using `setNotFoundHandler`, will
never trigger if the default route is overridden. This sets the handler for the
Fastify application, not just the current instance context. Use
[setNotFoundHandler](#setnotfoundhandler) if you want to customize 404 handling
instead.
-This method set the `defaultRoute` for the server. Note that, its purpose is
+This method sets the `defaultRoute` for the server. Note that, its purpose is
to interact with the underlying raw requests. Unlike other Fastify handlers, the
-arguments received are from type [RawRequest](./TypeScript.md#rawrequest) and
+arguments received are of type [RawRequest](./TypeScript.md#rawrequest) and
[RawReply](./TypeScript.md#rawreply) respectively.
```js
diff --git a/lib/route.js b/lib/route.js
index f48467de881..ae659c5bd04 100644
--- a/lib/route.js
+++ b/lib/route.js
@@ -89,9 +89,11 @@ function buildRouting (options) {
hasRoute,
prepareRoute,
getDefaultRoute: function () {
+ warning.emit('FSTDEP014')
return router.defaultRoute
},
setDefaultRoute: function (defaultRoute) {
+ warning.emit('FSTDEP014')
if (typeof defaultRoute !== 'function') {
throw new FST_ERR_DEFAULT_ROUTE_INVALID_TYPE()
}
diff --git a/lib/warnings.js b/lib/warnings.js
index 25fe27be8a5..3105f1e8558 100644
--- a/lib/warnings.js
+++ b/lib/warnings.js
@@ -25,4 +25,6 @@ warning.create('FastifyDeprecation', 'FSTDEP012', 'Request#context property acce
warning.create('FastifyDeprecation', 'FSTDEP013', 'Direct return of "trailers" function is deprecated. Please use "callback" or "async-await" for return value. The support of direct return will removed in `fastify@5`.')
+warning.create('FastifyDeprecation', 'FSTDEP014', 'You are trying to set/access the default route. This property is deprecated. Please, use setNotFoundHandler if you want to custom a 404 handler or the wildcard (*) to match all routes.')
+
module.exports = warning
diff --git a/test/default-route.test.js b/test/default-route.test.js
index 64de3c259cd..e77be678eb8 100644
--- a/test/default-route.test.js
+++ b/test/default-route.test.js
@@ -4,6 +4,26 @@ const t = require('tap')
const test = t.test
const Fastify = require('..')
+test('setDefaultRoute should emit a deprecation warning', t => {
+ t.plan(2)
+
+ const fastify = Fastify()
+ const defaultRoute = (req, res) => {
+ res.end('hello from defaultRoute')
+ }
+
+ process.on('warning', onWarning)
+ function onWarning (warning) {
+ t.equal(warning.name, 'FastifyDeprecation')
+ t.equal(warning.code, 'FSTDEP014')
+ }
+
+ t.teardown(() => process.removeListener('warning', onWarning))
+
+ fastify.setDefaultRoute(defaultRoute)
+ fastify.getDefaultRoute()
+})
+
test('should fail if defaultRoute is not a function', t => {
t.plan(1)