{"record":{"id":"91888eb6d6d7f07c","repo":"cube-js/cube","slug":"invalid-authorization-message-format","errorCode":null,"errorMessage":"Invalid authorization message format","messagePattern":"Invalid authorization message format","errorType":"validation","errorClass":"CubejsHandlerError","httpStatus":400,"severity":"error","filePath":"packages/cubejs-api-gateway/src/ws/subscription-server.ts","lineNumber":69,"sourceCode":"  protected deserializeMessage(message: any): any {\n    try {\n      return JSON.parse(message);\n    } catch (e: any) {\n      throw new CubejsHandlerError(400, 'Invalid JSON payload', e.message);\n    }\n  }\n\n  protected mapZodError(error: ZodError): string {\n    return error.issues\n      .map(e => (e.path.length ? `${e.path.join('.')}: ${e.message}` : e.message))\n      .join(', ');\n  }\n\n  protected validateMessage(message: object): WsMessage {\n    if ('authorization' in message) {\n      const result = authMessageSchema.safeParse(message);\n      if (!result.success) {\n        throw new CubejsHandlerError(400, 'Invalid authorization message format', this.mapZodError(result.error));\n      }\n\n      return result.data;\n    }\n\n    if ('unsubscribe' in message) {\n      const result = unsubscribeMessageSchema.safeParse(message);\n      if (!result.success) {\n        throw new CubejsHandlerError(400, 'Invalid unsubscribe message format', this.mapZodError(result.error));\n      }\n\n      return result.data;\n    }\n\n    const result = methodMessageSchema.safeParse(message);\n    if (!result.success) {\n      throw new CubejsHandlerError(400, 'Invalid message format', this.mapZodError(result.error));\n    }","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/cube-js/cube/blob/7d981676b36392fec34088b9afab6bdcad40207c/packages/cubejs-api-gateway/src/ws/subscription-server.ts#L51-L87","documentation":"When a WebSocket message contains an 'authorization' property, it must match the authMessageSchema (Zod): expected fields like token (and messageId per schema). Failures throw CubejsHandlerError(400, 'Invalid authorization message format') with a Zod-derived detail string listing the bad path and reason.","triggerScenarios":"Sending { authorization: ... } where authorization is not the expected object — e.g. authorization as a raw token string, missing required token/messageId fields, or wrong types per authMessageSchema.","commonSituations":"Custom WS clients passing { authorization: 'eyJ...' } instead of the schema's object shape; SDK version drift where the auth handshake shape changed; manually replaying protocol messages from docs of an older Cube version.","solutions":["Send the auth message in the schema's exact shape, e.g. { authorization: { token: '<jwt>' }, messageId: 'auth-1' } (check authMessageSchema in this package version).","Read the Zod detail after the error message — it names the exact field and rule violated.","Use the official @cubejs-client/ws-transport (WebSocketTransport) rather than hand-building protocol messages.","Bump the client and server packages to matching versions if the handshake shape changed in an upgrade."],"exampleFix":"// before\nsocket.send(JSON.stringify({ messageId: '1', authorization: 'my-jwt' }));\n// after\nsocket.send(JSON.stringify({ messageId: '1', authorization: { token: 'my-jwt' } }));","handlingStrategy":"validation","validationCode":"function isValidAuthMessage(msg: unknown): boolean {\n  const m = msg as any;\n  return typeof m === 'object' && m !== null &&\n    typeof m.messageId === 'string' &&\n    typeof m.authorization === 'object' && m.authorization !== null &&\n    typeof m.authorization.token === 'string';\n}","typeGuard":"function isAuthMessage(m: unknown): m is { messageId: string, authorization: { token: string } } {\n  return typeof m === 'object' && m !== null && 'authorization' in m &&\n    typeof (m as any).authorization?.token === 'string';\n}","tryCatchPattern":"try {\n  await handleMessage(frame);\n} catch (e) {\n  if (e.status === 400 && e.error === 'Invalid authorization message format') {\n    console.error('Auth frame rejected:', e.message); // Zod detail appended\n  } else throw e;\n}","preventionTips":["Use the official WebSocketTransport which formats the auth handshake correctly.","Keep client and server package versions aligned; auth schema can change between releases.","Verify the token is a string and required fields (messageId) are present before sending.","Test the handshake against your running Cube version, not documentation from another version."],"tags":["websocket","auth","validation","zod"],"backgroundTag":"invalid-message-format","analyzedSha":"7d981676b36392fec34088b9afab6bdcad40207c","analyzedAt":"2026-09-02T03:45:10.400Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}