diff --git a/docs/Reference/Server.md b/docs/Reference/Server.md
index c0f3b80f42..27fa1294c4 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 f48467de88..ae659c5bd0 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 25fe27be8a..3105f1e855 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 64de3c259c..4a8679e070 100644
--- a/test/default-route.test.js
+++ b/test/default-route.test.js
@@ -3,6 +3,51 @@
const t = require('tap')
const test = t.test
const Fastify = require('..')
+const warning = require('../lib/warnings')
+
+// Silence the standard warning logs. We will test the messages explicitly.
+process.removeAllListeners('warning')
+
+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)
+ warning.emitted.set('FSTDEP014', false)
+ })
+
+ fastify.setDefaultRoute(defaultRoute)
+})
+
+test('getDefaultRoute should emit a deprecation warning', t => {
+ t.plan(2)
+
+ const fastify = Fastify()
+
+ process.on('warning', onWarning)
+ function onWarning (warning) {
+ t.equal(warning.name, 'FastifyDeprecation')
+ t.equal(warning.code, 'FSTDEP014')
+ }
+
+ t.teardown(() => {
+ process.removeListener('warning', onWarning)
+ warning.emitted.set('FSTDEP014', false)
+ })
+
+ fastify.getDefaultRoute()
+})
test('should fail if defaultRoute is not a function', t => {
t.plan(1)