hcengineering/platform · error · Error

The "ws" package is required for NodeWebSocketFactory.

Error message

The "ws" package is required for NodeWebSocketFactory. 

What it means

NodeWebSocketFactory lazily requires the 'ws' package to create WebSocket connections in Node.js (browsers have a built-in WebSocket, Node does not). If 'ws' is not installed or cannot be resolved, the factory throws this Error immediately when a socket connection is attempted.

Source

Thrown at foundations/core/packages/api-client/src/socket/node.ts:26

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//
// See the License for the specific language governing permissions and
// limitations under the License.
//

import { type ClientSocket, type ClientSocketFactory } from '@hcengineering/client'

/** @public */
export const NodeWebSocketFactory: ClientSocketFactory = (url: string): ClientSocket => {
  // We need to override default factory with 'ws' one.
  // eslint-disable-next-line
  let WebSocket
  try {
    WebSocket = require('ws')
  } catch (error) {
    throw new Error('The "ws" package is required for NodeWebSocketFactory. ')
  }
  type WebSocketData = Parameters<typeof ws.on>[1]

  const ws = new WebSocket(url)

  const client: ClientSocket = {
    get readyState (): number {
      return ws.readyState
    },

    send: (data: string | ArrayBufferLike | Blob | ArrayBufferView): void => {
      if (data instanceof Blob) {
        void data.arrayBuffer().then((buffer) => {
          ws.send(buffer)
        })
      } else {
        ws.send(data)
      }

View on GitHub (pinned to 63e28dc964)

Solutions

1. npm install ws (and @types/ws for TypeScript) in the project that uses the api-client.
2. If bundling, mark 'ws' as external (webpack: externals; esbuild: --external:ws) and ship it in node_modules.
3. If deploying a Docker image, ensure production dependencies include ws (check node_modules/ws exists in the image).
4. Alternatively provide your own WebSocketFactory that supplies a WebSocket implementation available in your runtime.

Example fix

// before
const client = new PlatformClient(url, workspace, token) // throws at connect: The "ws" package is required...
// after
// 1) npm install ws
// 2) or supply an explicit factory
import ws from 'ws'
const client = new PlatformClient(url, workspace, token, undefined, {
  socketFactory: (url) => new WebSocket(url) // your own impl backed by 'ws'
})

// Run before creating a Node WebSocket client
let wsAvailable = false
try { require.resolve('ws'); wsAvailable = true } catch {}
if (!wsAvailable) {
  throw new Error('Install the "ws" package: npm install ws')
}

try {
  const client = createNodeWebSocketFactory(url)
} catch (e) {
  if (e instanceof Error && e.message.includes('"ws" package is required')) {
    // surface a clear install instruction to the operator
    console.error('Missing dependency: run `npm install ws @types/ws`')
  }
  throw e
}

When it happens

Trigger: Using PlatformWorkerWebSocketFactory / NodeWebSocketFactory in a Node environment where the 'ws' dependency is absent — e.g. a minimal install, pnpm strict node_modules hoisting issues, bundlers (webpack/esbuild) that didn't mark 'ws' as external, or running from a deployment image that pruned devDependencies.

Common situations: Docker image built with npm ci --omit=dev while 'ws' ended up a transitive/dev dep; serverless bundle missing node_modules; monorepo where @hcengineering/api-client is linked without its peer 'ws'; upgrading packages and dropping 'ws' from package.json.

Related errors

• Unsupported data type
• platform.status.ConnectionClosed
• Unexpected exception: could not detect node path
• ${reply.error}
• documentName must include workspace id

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/c413de867ca19e4b. Report an issue: GitHub.