medusajs/medusa · info

HMR_BIND_HOST is set but a custom hmr.server is already conf

Error message

HMR_BIND_HOST is set but a custom hmr.server is already configured. HMR_BIND_HOST will be ignored.

What it means

The admin bundler supports HMR_BIND_HOST to bind the HMR websocket server to a specific host (e.g. for Docker or remote dev). If your Vite config already defines server.hmr.server (a custom WebSocket server), the env var cannot be applied, so it logs this warning and continues — the custom hmr.server takes precedence and HMR_BIND_HOST is silently ignored.

Source

Thrown at packages/admin/admin-bundler/src/utils/config.ts:119

      pluginEnv[key.replace(/^PLUGIN_/, "")] = value
    }
  }
  baseConfig.define!["process.env"] = JSON.stringify(pluginEnv)

  let finalConfig = baseConfig
  if (options.vite) {
    const customConfig = options.vite(baseConfig)
    finalConfig = mergeConfig(baseConfig, customConfig)
  }

  // Handle HMR_BIND_HOST after merge to detect conflicts
  if (process.env.HMR_BIND_HOST) {
    if (
      finalConfig.server?.hmr &&
      typeof finalConfig.server.hmr === "object" &&
      finalConfig.server.hmr.server
    ) {
      console.warn(
        "HMR_BIND_HOST is set but a custom hmr.server is already configured. HMR_BIND_HOST will be ignored."
      )
    } else {
      const { createServer } = require("http")
      const hmrServer = createServer()
      hmrServer.listen(hmrPort, process.env.HMR_BIND_HOST)
      if (!finalConfig.server) {
        finalConfig.server = {}
      }
      if (
        !finalConfig.server.hmr ||
        typeof finalConfig.server.hmr !== "object"
      ) {
        finalConfig.server.hmr = {}
      }
      finalConfig.server.hmr.server = hmrServer
    }
  }

View on GitHub (pinned to 5e06e544a2)

Solutions

1. Remove the custom server.hmr.server from your Vite config and rely on HMR_BIND_HOST alone
2. Or drop HMR_BIND_HOST and configure the host directly on your custom hmr.server
3. Verify after restart that HMR connects from your environment (container/remote host) via the browser console
4. The warning is harmless if your existing hmr.server already binds the desired host — no action needed

Example fix

// before (vite.config / admin config)
server: { hmr: { server: myHttpServer } }
# plus HMR_BIND_HOST=0.0.0.0 → warning, env ignored

// after — pick one mechanism
server: { hmr: { server: myHttpServer, host: "0.0.0.0" } }
# or remove hmr.server entirely and keep HMR_BIND_HOST=0.0.0.0

if (process.env.HMR_BIND_HOST && customViteConfig?.server?.hmr?.server) {
  console.log("HMR_BIND_HOST will be ignored — configure hmr.server.host instead")
}

const hasCustomHmrServer = (c) =>
  Boolean(c?.server?.hmr && typeof c.server.hmr === "object" && c.server.hmr.server)

null

When it happens

Trigger: Starting the admin dev/bundling process with HMR_BIND_HOST set while the effective Vite config contains an object server.hmr with a non-empty server property (from user config or merged defaults).

Common situations: Docker/containerized development where HMR_BIND_HOST=0.0.0.0 is recommended, but a template or prior customization also set hmr.server; upgrading admin-bundler where default config now includes an hmr object.

Related errors

• Job registration requires id. Received: ${JSON.stringify(dat
• Job registration requires sourcePath. Received: ${JSON.strin
• Job registration requires config.name. Received: ${JSON.stri
• Step registration requires id. Received: ${JSON.stringify(da
• Step registration requires either sourcePath or workflowId.

AI-assisted analysis of medusajs/medusa@5e06e544a2 (2026-08-27). Data as JSON: /api/errors/8cdc12d21d5c315b. Report an issue: GitHub.