beekeeper-studio/beekeeper-studio · error · SyntaxError

String should only contain hex characters

Error message

String should only contain hex characters

What it means

hexToUint8Array checks each two-character slice against a NOT_HEX regex as it decodes. A SyntaxError is thrown when any slice contains characters outside [0-9a-fA-F], since only hex digits can be converted to bytes.

Source

Thrown at apps/ui-kit/lib/utils/binary.ts:40

var NOT_HEX = /[^\da-f]/i;
var exec = uncurryThis(NOT_HEX.exec);
var stringSlice = uncurryThis(''.slice);

/**
  * Extracted from https://github.com/zloirock/core-js/blob/master/packages/core-js/internals/uint8-from-hex.js
  * FIXME we don't need this soon after `UInt8Array.prototype.fromHex` is
  * implemented. See https://github.com/tc39/proposal-arraybuffer-base64
  */
export function hexToUint8Array(string: string, into?: any): Uint8Array {
  var stringLength = string.length;
  if (stringLength % 2 !== 0) throw new SyntaxError('String should be an even number of characters');
  var maxLength = into ? min(into.length, stringLength / 2) : stringLength / 2;
  var bytes = into || new Uint8Array(maxLength);
  var read = 0;
  var written = 0;
  while (written < maxLength) {
    var hexits = stringSlice(string, read, read += 2);
    if (exec(NOT_HEX, hexits)) throw new SyntaxError('String should only contain hex characters');
    bytes[written++] = parseInt(hexits, 16);
  }
  return bytes
}

View on GitHub (pinned to 4e3e03e322)

Solutions

1. Sanitize input before calling: strip '0x' prefix, whitespace, and separators (e.g. string.replace(/0x|[\s-]/g, '')).
2. Pre-validate with /^[0-9a-fA-F]+$/.test(hex) and show a validation error for user input.
3. Fix the data source emitting non-hex encodings (e.g. decode base64 or escapes first).
4. Wrap in try/catch to convert the SyntaxError into a friendly message.

Example fix

// before
const bytes = hexToUint8Array(rawHex); // "0x1a2b-3c"
// after
const cleanHex = rawHex.replace(/^0x|[\s-]/g, '');
if (!/^[0-9a-fA-F]+$/.test(cleanHex)) throw new TypeError('invalid hex');
const bytes = hexToUint8Array(cleanHex);

const clean = hex.replace(/^0x/[i], '').replace(/[\s_-]/g, '');
if (!/^[0-9a-fA-F]+$/.test(clean)) throw new TypeError('invalid hex characters');

function isHexString(s: unknown): s is string {
  return typeof s === 'string' && /^[0-9a-fA-F]+$/.test(s);
}

try {
  const bytes = hexToUint8Array(hex);
} catch (e) {
  if (e instanceof SyntaxError && /hex characters/.test(e.message)) {
    throw new TypeError(`Non-hex input: ${JSON.stringify(hex)}`);
  }
  throw e;
}

When it happens

Trigger: Passing a string containing non-hex characters such as '0x1a2b' (0x prefix), whitespace, '-', 'zz', or UUID formatting ('1a2b-3c4d') to hexToUint8Array.

Common situations: Hex values copied with '0x' prefixes or separators; database drivers returning bytea/hex with escapes; user-pasted keys containing spaces or typos; forgetting that binary output is uppercase-safe but not separator-safe.

Related errors

• String should be an even number of characters
• No username provided
• Invalid authentication mode: ${auth.mode}
• authId is required
• DynamoDB IAM key authentication requires a non-empty Access

AI-assisted analysis of beekeeper-studio/beekeeper-studio@4e3e03e322 (2026-08-31). Data as JSON: /api/errors/7b930ca8e095f47c. Report an issue: GitHub.