brianc/node-postgres · error · Error

Binary mode not supported yet

Error message

Binary mode not supported yet

What it means

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.

Source

Thrown at packages/pg-protocol/src/parser.ts:89

  EmptyQuery = 0x49, // I
  CopyIn = 0x47, // G
  CopyOut = 0x48, // H
  CopyDone = 0x63, // c
  CopyData = 0x64, // d
}

export type MessageCallback = (msg: BackendMessage) => void

export class Parser {
  private buffer: Buffer = emptyBuffer
  private bufferLength: number = 0
  private bufferOffset: number = 0
  private reader = new BufferReader()
  private mode: Mode

  constructor(opts?: StreamOptions) {
    if (opts?.mode === 'binary') {
      throw new Error('Binary mode not supported yet')
    }
    this.mode = opts?.mode || 'text'
  }

  public parse(buffer: Buffer, callback: MessageCallback) {
    this.mergeBuffer(buffer)
    const bufferFullLength = this.bufferOffset + this.bufferLength
    let offset = this.bufferOffset
    while (offset + HEADER_LENGTH <= bufferFullLength) {
      // code is 1 byte long - it identifies the message type
      const code = this.buffer[offset]
      // length is 1 Uint32BE - it is the length of the message EXCLUDING the code
      const length = this.buffer.readUInt32BE(offset + CODE_LENGTH)
      const fullMessageLength = CODE_LENGTH + length
      if (fullMessageLength + offset <= bufferFullLength) {
        const message = this.handlePacket(offset + HEADER_LENGTH, code, length, this.buffer)
        callback(message)
        offset += fullMessageLength

View on GitHub (pinned to c5e8c9a57b)

Solutions

  1. Do not pass mode: 'binary' to the Parser constructor; use the default text mode.
  2. 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.
  3. If you are maintaining a fork that needs full binary protocol support, you must implement binary row decoding in the parser yourself.

Example fix

// before (direct pg-protocol use)
import { Parser } from 'pg-protocol';
const parser = new Parser({ mode: 'binary' });

// after
const parser = new Parser(); // text mode (default)
// for binary columns, use the client-level option instead:
const client = new pg.Client({ binary: true });
Defensive patterns

Strategy: validation

Validate before calling

import { Parser } from 'pg-protocol';

function createParser(opts) {
  if (opts?.mode === 'binary') {
    throw new Error('Binary parser mode is unsupported; use the default text mode or client-level binary option.');
  }
  return new Parser(opts);
}

Type guard

function isSupportedParserMode(mode) {
  return mode === undefined || mode === 'text';
}

Prevention

When it happens

Trigger: 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.

Common situations: 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).

Related errors

AI-assisted analysis of brianc/node-postgres@c5e8c9a57b (2026-08-03). Data as JSON: /data/errors/48f81cf62764eb70.json. Report an issue: GitHub.