{"id":"48f81cf62764eb70","repo":"brianc/node-postgres","slug":"binary-mode-not-supported-yet","errorCode":null,"errorMessage":"Binary mode not supported yet","messagePattern":"Binary mode not supported yet","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/pg-protocol/src/parser.ts","lineNumber":89,"sourceCode":"  EmptyQuery = 0x49, // I\n  CopyIn = 0x47, // G\n  CopyOut = 0x48, // H\n  CopyDone = 0x63, // c\n  CopyData = 0x64, // d\n}\n\nexport type MessageCallback = (msg: BackendMessage) => void\n\nexport class Parser {\n  private buffer: Buffer = emptyBuffer\n  private bufferLength: number = 0\n  private bufferOffset: number = 0\n  private reader = new BufferReader()\n  private mode: Mode\n\n  constructor(opts?: StreamOptions) {\n    if (opts?.mode === 'binary') {\n      throw new Error('Binary mode not supported yet')\n    }\n    this.mode = opts?.mode || 'text'\n  }\n\n  public parse(buffer: Buffer, callback: MessageCallback) {\n    this.mergeBuffer(buffer)\n    const bufferFullLength = this.bufferOffset + this.bufferLength\n    let offset = this.bufferOffset\n    while (offset + HEADER_LENGTH <= bufferFullLength) {\n      // code is 1 byte long - it identifies the message type\n      const code = this.buffer[offset]\n      // length is 1 Uint32BE - it is the length of the message EXCLUDING the code\n      const length = this.buffer.readUInt32BE(offset + CODE_LENGTH)\n      const fullMessageLength = CODE_LENGTH + length\n      if (fullMessageLength + offset <= bufferFullLength) {\n        const message = this.handlePacket(offset + HEADER_LENGTH, code, length, this.buffer)\n        callback(message)\n        offset += fullMessageLength","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/brianc/node-postgres/blob/c5e8c9a57bff6d9160ec5dbd5c4f4c1e4c460711/packages/pg-protocol/src/parser.ts#L71-L107","documentation":"Thrown by the pg-protocol Parser constructor (parser.ts:88-89) when opts.mode === 'binary'. The library's wire-protocol parser only implements text-mode result decoding; binary result format was never implemented for the low-level message parser. This is distinct from the client-level Query.binary option (which uses the extended protocol's binary format flag at a higher layer). This error indicates the internal parser was explicitly constructed in an unsupported mode.","triggerScenarios":"Constructing new Parser({ mode: 'binary' }) directly from the pg-protocol package. Internally, the Connection class passes a mode option derived from client configuration; reaching this throw means the protocol stream was told to decode all messages in binary, which the parser cannot do.","commonSituations":"Almost never hit by application developers — it is an internal guard. Could surface if a fork or direct pg-protocol consumer sets mode:'binary'. The client-level `new Client({ binary: true })` option works fine and does NOT hit this path (it sets per-column binary format via the extended protocol, not the parser mode).","solutions":["Do not pass mode: 'binary' to the Parser constructor; use the default text mode.","If you need binary column decoding, use the client-level binary option (new Client({ binary: true })) or per-query { binary: true } which operates at the extended-protocol layer, not the parser mode.","If you are maintaining a fork that needs full binary protocol support, you must implement binary row decoding in the parser yourself."],"exampleFix":"// before (direct pg-protocol use)\nimport { Parser } from 'pg-protocol';\nconst parser = new Parser({ mode: 'binary' });\n\n// after\nconst parser = new Parser(); // text mode (default)\n// for binary columns, use the client-level option instead:\nconst client = new pg.Client({ binary: true });","handlingStrategy":"validation","validationCode":"import { Parser } from 'pg-protocol';\n\nfunction createParser(opts) {\n  if (opts?.mode === 'binary') {\n    throw new Error('Binary parser mode is unsupported; use the default text mode or client-level binary option.');\n  }\n  return new Parser(opts);\n}","typeGuard":"function isSupportedParserMode(mode) {\n  return mode === undefined || mode === 'text';\n}","tryCatchPattern":null,"preventionTips":["Never construct the low-level Parser with mode:'binary' — it is unimplemented.","Use the Client-level binary option ({ binary: true }) for binary column results; it works at the extended-protocol layer.","If maintaining a fork that needs binary protocol parsing, implement it in the parser before enabling the mode."],"tags":["protocol","binary","unsupported","internal"],"analyzedSha":"c5e8c9a57bff6d9160ec5dbd5c4f4c1e4c460711","analyzedAt":"2026-08-03T18:47:28.334Z","schemaVersion":2}