cube-js/cube · warning · UserError

Method is required

Error message

Method is required

What it means

The WebSocket subscription server validates every incoming message before dispatching it to a registered method. A message without a `method` field cannot be routed, so handleMessage throws UserError('Method is required') before any handler lookup. This is an input-validation error sent back to the WS client rather than a server crash.

Source

Thrown at packages/cubejs-api-gateway/src/ws/subscription-server.ts:154

      if (!message.messageId) {
        throw new UserError('messageId is required');
      }

      authContext = await this.subscriptionStore.getAuthContext(connectionId);
      if (!authContext) {
        await this.sendMessage(
          connectionId,
          {
            messageId: message.messageId,
            message: { error: 'Not authorized' },
            status: 403
          }
        );
        return;
      }

      if (!message.method) {
        throw new UserError('Method is required');
      }

      if (!methodParams.hasOwnProperty(message.method)) {
        throw new UserError(`Unsupported method: ${message.method}`);
      }

      const subscriptionId = message.messageId;
      const baseRequestId = message.requestId || `${connectionId}-${subscriptionId}`;
      const requestId = `${baseRequestId}-span-${uuidv4()}`;

      context = await this.apiGateway.contextByReq(
        // TODO: We need to standardize type for WS request type
        message as any,
        authContext.securityContext,
        requestId
      );

      this.apiGateway.log({

View on GitHub (pinned to 7d981676b3)

Solutions

1. Add a `method` field to the WS message (e.g. { method: 'load', ... }) matching a key in methodParams
2. Verify the client uses the official Cube WebSocket transport which always sets `method`
3. Log the raw incoming message on the client to confirm what is actually serialized

Example fix

// before
socket.send(JSON.stringify({ messageId: '1', query }))
// after
socket.send(JSON.stringify({ messageId: '1', method: 'load', params: { query } }))

function sendWsMessage(socket, msg) {
  if (typeof msg.method !== 'string' || !msg.method) throw new TypeError('WS message requires a method field')
  socket.send(JSON.stringify(msg))
}

function hasMethod(m: unknown): m is { method: string } {
  return !!m && typeof m === 'object' && typeof (m as any).method === 'string' && (m as any).method.length > 0
}

socket.on('message', raw => {
  const msg = JSON.parse(raw)
  if (!msg.method) return console.error('Cube WS: method field is required in', msg)
  // dispatch
})

When it happens

Trigger: Client sends a JSON WS message lacking the `method` property, e.g. `{ messageId: '1', params: {...} }`, via the subscription transport.

Common situations: Hand-rolled WebSocket clients, custom frontends not using @cubejs-client/ws, typos like `Method`, or messages that only carry a payload without specifying which API method to invoke.

Related errors

• Invalid message format
• messageId is required
• Invalid JSON payload
• Invalid authorization message format
• Invalid unsubscribe message format

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/adebc50d75102882. Report an issue: GitHub.