SubtitleEdit/subtitleedit · warning · InvalidOperationException

Unknown byte ({b}) in subtitle file @ binary offset {index}.

Error message

Unknown byte ({b}) in subtitle file @ binary offset {index}.

What it means

Thrown by Pac.GetHebrewString when a byte is not a printable ASCII (0x20-0x7F excluding comma 0x2C) and is not present in the HebrewCodes map, with Pac.ThrowOnError=true. The default (false) returns an empty string. Reports the byte value and offset.

Source

Thrown at src/libse/SubtitleFormats/Pac.cs:2576

            return arabicCharacter;
        }

        public static string GetHebrewString(byte[] buffer, ref int index)
        {
            var b = buffer[index];
            if (b >= 0x20 && b < 0x80 && b != 44)
            {
                return Encoding.ASCII.GetString(buffer, index, 1);
            }

            if (HebrewCodes.ContainsKey(b))
            {
                return HebrewCodes[b].Character;
            }

            if (ThrowOnError)
            {
                throw new InvalidOperationException($"Unknown byte ({b}) in subtitle file @ binary offset {index}.");
            }

            return string.Empty;
        }

        private static bool TryGetMappedCharacter(Dictionary<int, SpecialCharacter> map, byte[] buffer, ref int index, out string result)
        {
            var b = buffer[index];

            result = string.Empty;
            if (map.ContainsKey(b))
            {
                result = map[b].Character;
            }

            if (buffer.Length > index + 2)
            {
                var code = b * 256 + buffer[index + 1];

View on GitHub (pinned to 17a9f07487)

Solutions

1. Keep Pac.ThrowOnError = false (default) to skip unmapped bytes.
2. Confirm the file's language is Hebrew and select the correct codepage.
3. Re-acquire the file if corruption is likely.
4. Extend HebrewCodes for the unmapped byte if it is a legitimate glyph.

Example fix

// before
Pac.ThrowOnError = true;
// after
Pac.ThrowOnError = false;

// Tolerant mode skips unmapped Hebrew bytes
Pac.ThrowOnError = false;
new Pac().LoadSubtitle(sub, lines, fileName);

Pac.ThrowOnError = true;
try
{
    new Pac().LoadSubtitle(sub, lines, fileName);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown byte"))
{
    logger.Warning(ex.Message); // byte value and offset included
}

When it happens

Trigger: Decoding a PAC Hebrew track where a byte is outside the Hebrew glyph table and printable-ASCII range — e.g. a control byte, a comma (0x2C is explicitly excluded), or an unmapped high byte. Only throws when ThrowOnError is set.

Common situations: Codepage misclassification (file is not Hebrew), corrupt bytes, or a Hebrew variant whose glyph table differs from this build's HebrewCodes.

Related errors

• Unknown byte ({buffer[index]}) in subtitle file @ binary off
• Unknown byte (0x{b:X2}) in subtitle file @ binary offset {in
• Error in paragraph {p.StartTime} after '{sb}': {ex.Message}
• Invalid ASSA time code: {time}
• Unknown time format '{timeFormat}'

AI-assisted analysis of SubtitleEdit/subtitleedit@17a9f07487 (2026-08-13). Data as JSON: /api/errors/a7a4ce3b90d22b45. Report an issue: GitHub.