How to Fix webpack-dev-server 'Invalid Configuration Object' After Upgrading to Create React App 5.0

Threat/Impact Level: HIGH | Downtime Risk: HIGH | Time to Fix: 5–15 mins

---

TL;DR

• What broke: CRA 5.0 ships webpack-dev-server v4, which completely dropped or renamed ~12 config keys from v3. Any devServer block or setupProxy.js written for CRA 4.x will throw Invalid configuration object and refuse to start.
• How to fix it: Audit your devServer config and src/setupProxy.js for deprecated keys — replace before/after with setupMiddlewares, disableHostCheck with allowedHosts, and old socket env vars with client.webSocketURL.
• Fast path: Use our Client-Side Sandbox below to auto-refactor this — paste your config and get a corrected diff without sending your proxy targets or internal hostnames to any third-party server.

---

The Incident (What Does the Error Mean?)

Your terminal output looks exactly like this:

Invalid configuration object. Webpack-dev-server has been initialized using a
configuration object that does not match the API schema.
 - configuration.disableHostCheck is not allowed
 - configuration.before is not allowed
 - configuration has an unknown property 'sockHost'

Or a variant listing transportMode, injectClient, after, features, or watchOptions.poll. The dev server refuses to boot entirely — react-scripts start exits non-zero, your local environment is dead, and any CI pipeline running smoke tests against the dev server is now broken too.

This is not a transient error. webpack-dev-server v4 (bundled in CRA 5) enforces strict JSON-schema validation against its config at startup. Any unrecognized or removed key is a hard failure.

---

The Blast Radius

This isn't a runtime warning you can defer. The immediate casualties:

• All local development stops. Every engineer on the team who pulls the upgraded branch is blocked.
• CI preview environments fail. If your pipeline runs react-scripts start for integration or Cypress tests, every build fails.
• Proxy misconfigurations go undetected. Teams often "fix" the error by deleting the entire devServer block, silently removing CORS proxy rules, auth header injection, or WebSocket upgrade configs — causing subtle API failures that surface later.
• The disableHostCheck: true removal is a security correction you should not re-implement carelessly. Its replacement, allowedHosts: 'all', carries the same DNS rebinding attack risk if used in shared/cloud dev environments. Scope it properly.

---

How to Fix It

Deprecated Key Migration Map

CRA 4 / WDS v3 Key	WDS v4 Replacement
disableHostCheck: true	allowedHosts: 'all' (use cautiously)
before(app, server)	setupMiddlewares(middlewares, devServer)
after(app, server)	setupMiddlewares (append to array)
sockHost / sockPort / sockPath	client.webSocketURL: { hostname, port, pathname }
transportMode: 'ws'	webSocketServer: 'ws'
injectClient / injectHot	Removed — use hot: true
https: { key, cert, ca }	server: { type: 'https', options: { key, cert, ca } }
watchOptions: { poll: 1000 }	watchFiles + watchOptions restructured under root

---

Basic Fix — src/setupProxy.js

 const { createProxyMiddleware } = require('http-proxy-middleware');

- module.exports = function(app) {
-   app.use('/api', createProxyMiddleware({ target: 'http://localhost:5000', changeOrigin: true }));
- };
+ module.exports = function(app, server) {
+   // WDS v4: function signature unchanged for setupProxy.js — this file is fine.
+   // Ensure http-proxy-middleware is v2.x (not v1.x) for CRA 5 compatibility.
+   app.use('/api', createProxyMiddleware({ target: 'http://localhost:5000', changeOrigin: true }));
+ };

Note: setupProxy.js itself doesn't change signature — but if you're on http-proxy-middleware v1.x, upgrade to v2.x. The pathRewrite and router option shapes changed.

---

Basic Fix — craco.config.js or custom devServer block

 module.exports = {
   devServer: {
-    disableHostCheck: true,
+    allowedHosts: 'auto',

-    before(app, server) {
-      app.use('/mock', mockMiddleware);
-    },
+    setupMiddlewares(middlewares, devServer) {
+      devServer.app.use('/mock', mockMiddleware);
+      return middlewares;
+    },

-    sockHost: 'dev.internal.example.com',
-    sockPort: 443,
-    sockPath: '/ws',
+    client: {
+      webSocketURL: {
+        hostname: 'dev.internal.example.com',
+        port: 443,
+        pathname: '/ws',
+      },
+    },

-    https: {
-      key: fs.readFileSync('./certs/key.pem'),
-      cert: fs.readFileSync('./certs/cert.pem'),
-    },
+    server: {
+      type: 'https',
+      options: {
+        key: fs.readFileSync('./certs/key.pem'),
+        cert: fs.readFileSync('./certs/cert.pem'),
+      },
+    },

-    transportMode: 'ws',
-    injectClient: false,
-    injectHot: true,
+    webSocketServer: 'ws',
+    hot: true,
   },
 };

---

Enterprise Best Practice

Do not use allowedHosts: 'all' in shared cloud dev environments or remote workspaces (Gitpod, Codespaces, Cloud9). This re-opens the DNS rebinding vector that disableHostCheck was criticized for. Instead:

-    allowedHosts: 'all',
+    allowedHosts: [
+      'localhost',
+      '.internal.yourcompany.com',  // wildcard subdomain scope
+    ],

For teams using CRACO or react-app-rewired, pin the override tool version explicitly:

 // package.json
-  "@craco/craco": "^6.4.3",
+  "@craco/craco": "^7.1.0",

CRACO v6 does not support CRA 5 / WDS v4. This is a second, silent failure mode that manifests as the same Invalid configuration object error.

---

💡 Tired of pasting proprietary configs into ChatGPT? Generic AI tools log your company's ARNs, DB strings, and private keys. StackEngine is a zero-backend, pure Client-Side WASM utility. Drop your failing config into the sandbox above. We redact your secrets locally in the browser and auto-generate the refactored code using your own API key.

---

Prevention in CI/CD

1. Lock the exact CRA and WDS versions in package.json:

"react-scripts": "5.0.1",
"webpack-dev-server": "4.15.1"

Never use ^ on react-scripts in a team repo. A minor bump here is a breaking infrastructure change.

2. Add a config validation step to your pipeline:

# .github/workflows/ci.yml
- name: Validate webpack-dev-server config schema
  run: |
    npx webpack-dev-server --config webpack.config.js --dry-run 2>&1 | \
    grep -i 'invalid configuration' && exit 1 || exit 0

3. Use eslint-plugin-react-app + a custom schema lint rule to catch deprecated devServer keys at PR time before they reach main.

4. Checkov / Semgrep custom rule for teams managing CRA configs as IaC:

# semgrep rule: detect deprecated WDS v3 keys
rules:
  - id: wds-v3-deprecated-disableHostCheck
    patterns:
      - pattern: disableHostCheck: ...
    message: "disableHostCheck removed in webpack-dev-server v4. Use allowedHosts."
    languages: [javascript, typescript]
    severity: ERROR

5. Renovate/Dependabot grouping: Group react-scripts upgrades into a dedicated PR with a mandatory reviewer — never auto-merge.