Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

webpack-dev-server says the options object does not match the API schema

ErrorInvalid 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.

  • Applies to webpack-dev-server 5, webpack 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.js
  2. 2Match what you see, then jump to its fix

    1. 1options has an unknown property 'contentBase' (or 'publicPath', 'overlay', 'disableHostCheck')contentBase and other v3 optionsFix
    2. 2The error names onBeforeSetupMiddleware or onAfterSetupMiddlewareonBeforeSetupMiddleware or onAfterSetupMiddleware under v5Fix
    3. 3options has an unknown property 'https' or 'http2'http2 or https flags under v5Fix
    4. 4The error names the proxy option and your proxy is an objectproxy written as an object under v5Fix

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-server

2Fix

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 serve

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 4

onBeforeSetupMiddleware or onAfterSetupMiddleware under v5

1Check

Version 5 removed these two hooks.

grep -n "SetupMiddleware" webpack.config.js

2Fix

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 serve

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

http2 or https flags under v5

1Check

Search for them in devServer.

grep -n "https\|http2" webpack.config.js

2Fix

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 serve

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 4

proxy written as an object under v5

1Check

Look at the proxy block.

grep -n -A8 "proxy" webpack.config.js

2Fix

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 serve

Confirmed by raw.githubusercontent.com

Did this fix it?

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

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.