webpack-dev-server says the options object does not match the API schema
Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.Short answer
Webpack-dev-server validates devServer options when it starts. The error names the property it rejects. This nearly always follows an upgrade, because v4 and v5 removed old options: contentBase became static, https moved into server, and the middleware hooks became setupMiddlewares. Rename the option that the message names.
Fix it fast
1Find out which cause you have
Note the property name after unknown property. Then see which devServer keys your config sets.
grep -n -A25 "devServer" webpack.config.js2Match what you see, then jump to its fix
- 1
options has an unknown property 'contentBase' (or 'publicPath', 'overlay', 'disableHostCheck')contentBase and other v3 optionsFix - 2
The error names onBeforeSetupMiddleware or onAfterSetupMiddlewareonBeforeSetupMiddleware or onAfterSetupMiddleware under v5Fix - 3
options has an unknown property 'https' or 'http2'http2 or https flags under v5Fix - 4
The error names the proxy option and your proxy is an objectproxy written as an object under v5Fix
- 1
What does the error look like?
Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.
Cause 1 of 4
contentBase and other v3 options
1Check
Version 4 moved several v3 options. Check the installed version.
npm ls webpack-dev-server2Fix
Use static for contentBase, devMiddleware for publicPath, client.overlay for overlay, and allowedHosts for disableHostCheck.
const path = require('path');
module.exports = {
devServer: {
static: { directory: path.resolve(__dirname, 'public') },
client: { overlay: true },
allowedHosts: 'all',
},
};3Verify
Start the server again.
npx webpack serveConfirmed by raw.githubusercontent.com
Cause 2 of 4
onBeforeSetupMiddleware or onAfterSetupMiddleware under v5
1Check
Version 5 removed these two hooks.
grep -n "SetupMiddleware" webpack.config.js2Fix
Use setupMiddlewares. Add with unshift to run before the others, and with push to run after.
devServer: {
setupMiddlewares: (middlewares, devServer) => {
middlewares.push({
name: 'after-middleware',
path: '/some/path',
middleware: (req, res) => { res.json({ ok: true }); },
});
return middlewares;
},
},3Verify
Start the server and request that path.
npx webpack serveConfirmed by raw.githubusercontent.com
Cause 3 of 4
http2 or https flags under v5
1Check
Search for them in devServer.
grep -n "https\|http2" webpack.config.js2Fix
Version 5 takes one server option with a type and options.
devServer: {
server: {
type: 'https',
options: { key: './server.key', cert: './server.crt' },
},
},3Verify
Start the server and open the https address.
npx webpack serveConfirmed by raw.githubusercontent.com
Cause 4 of 4
proxy written as an object under v5
1Check
Look at the proxy block.
grep -n -A8 "proxy" webpack.config.js2Fix
Write proxy as an array, with context listing the paths.
devServer: {
proxy: [
{ context: ['/api'], target: 'http://localhost:3000', changeOrigin: true },
],
},3Verify
Start the server and call an /api path.
npx webpack serveConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Read the migration guide before raising the major version of webpack-dev-server.
- Pin the version in package.json and upgrade on purpose.
- Keep devServer small and prefer defaults.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
webpack says the configuration object does not match the API schema
Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema.
Webpack checks your config against a schema before it builds.
3 causes, each with a fixWeb apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fix