What causes "invalid bytes ip, not a Buffer" in lionsoul2014/ip2region?

Wrap the value with Buffer.from(ipBytes) before calling ipToString (Buffer.from accepts Uint8Array/array/base64/hex strings with an encoding).

lionsoul2014/ip2region · error · Error

invalid bytes ip, not a Buffer

Error message

invalid bytes ip, not a Buffer

What it means

ipToString converts a raw 4-byte or 16-byte Buffer into a human-readable IPv4/IPv6 string. The library requires the argument to be a Node Buffer; any other value (string, Uint8Array, Array, null) is rejected up front with this TypeError-like Error so downstream byte indexing cannot silently misbehave.

Source

Thrown at binding/javascript/util.js:220

        if (_.length == 0) {
            _.push('');
        }

        _.push(''); // empty for double colon

        // make sure there is an empty tail
        if (i == ps.length && _.length < ps.length) {
            _.push('');
        }
    }

    return _.join(':');
}

// bytes ip to humen-readable string ip
export function ipToString(ipBytes, compress) {
    if (!Buffer.isBuffer(ipBytes)) {
        throw new Error('invalid bytes ip, not a Buffer');
    }

    if (ipBytes.length == 4) {
        return _ipv4_to_string(ipBytes, compress);
    } else if (ipBytes.length == 16) {
        return _ipv6_to_string(ipBytes, compress);
    } else {
        throw new Error('invalid bytes ip with length not 4 or 16');
    }
}

export function ipBytesString(ipBytes) {
    if (!Buffer.isBuffer(ipBytes)) {
        throw new Error('invalid bytes ip, not a Buffer');
    }

    let ps = [];
    for (var i = 0; i < ipBytes.length; i++) {

View on GitHub (pinned to c1a1fc7d59)

Solutions

Wrap the value with Buffer.from(ipBytes) before calling ipToString (Buffer.from accepts Uint8Array/array/base64/hex strings with an encoding).
If the source is a base64/hex string, decode explicitly: Buffer.from(str, 'hex') or Buffer.from(str, 'base64').
Check that the bytes actually come from the xdb searcher's result object rather than a hand-built value.
In TypeScript, type the parameter as Buffer and let the compiler catch mismatches.

Example fix

// before
const ip = ipToString(JSON.parse(raw).ipBytes); // array -> throws
// after
const bytes = Buffer.from(JSON.parse(raw).ipBytes);
const ip = ipToString(bytes);

Defensive patterns

Strategy: type-guard

Validate before calling

function isIpBuffer(b) { return Buffer.isBuffer(b) && (b.length === 4 || b.length === 16); }
if (!isIpBuffer(ipBytes)) throw new TypeError('expected 4/16-byte Buffer');

Type guard

function isIpBytes(v) { return Buffer.isBuffer(v) && (v.length === 4 || v.length === 16); }

Try / catch

try {
  const ip = ipToString(ipBytes);
} catch (e) {
  if (e.message.includes('invalid bytes ip')) {
    ipBytes = Buffer.from(ipBytes ?? []);
    // retry or log and skip
  } else throw e;
}

Prevention

Keep IP bytes as Buffers end-to-end; convert at system boundaries with Buffer.from.
Never send Buffers through JSON.stringify/parse; encode as base64/hex instead.
In TypeScript, type IP byte fields as Buffer, not Uint8Array.

When it happens

Trigger: Calling ipToString(ipBytes, compress) with a non-Buffer value: e.g. passing a hex string, a plain array of bytes from JSON, a Uint8Array from WebCrypto, or null/undefined when a lookup result field was misread.

Common situations: Developers deserialize IP bytes from an external store (DB blob, JSON) as arrays or base64 strings and pass them straight in; TypeScript users using Uint8Array instead of Buffer; forgetting to call Buffer.from() on data read from a file split at manual offsets.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of lionsoul2014/ip2region@c1a1fc7d59 (2026-09-02). Data as JSON: /api/errors/8b07499954d26719. Report an issue: GitHub.