SubtitleEdit/subtitleedit · warning · InvalidOperationException

Unknown byte ({buffer[index]}) in subtitle file @ binary off

Error message

Unknown byte ({buffer[index]}) in subtitle file @ binary offset {index}.

What it means

Thrown by Pac.GetArabicString when a byte in the stream does not map to any known Arabic (or combined Arabic) character and the static flag Pac.ThrowOnError is true. Without the flag (the default false) it silently returns an empty string instead. The message reports the offending byte value and the binary offset.

Source

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

        {
            var arabicCharacter = GetNextArabicCharacter(buffer, ref index);

            if (arabicCharacter.HasValue && arabicCharacter.Value.SwitchOrder)
            {
                // if we have a special character we must fetch the next one and move it before the current special one
                var tempIndex = index + 1;
                var nextArabicCharacter = GetNextArabicCharacter(buffer, ref tempIndex);
                if (buffer[tempIndex] >= 0x80 && nextArabicCharacter != null)
                {
                    index = tempIndex;
                    var combined = $"{nextArabicCharacter.Value.Character}{arabicCharacter.Value.Character}";
                    return combined;
                }
            }

            if (ThrowOnError && !arabicCharacter.HasValue)
            {
                throw new InvalidOperationException($"Unknown byte ({buffer[index]}) in subtitle file @ binary offset {index}.");
            }

            return arabicCharacter.HasValue
                ? arabicCharacter.Value.Character
                : string.Empty;
        }

        private static SpecialCharacter? GetNextArabicCharacter(byte[] buffer, ref int index)
        {
            if (index >= buffer.Length)
            {
                return null;
            }

            var b = buffer[index];
            SpecialCharacter? arabicCharacter = null;
            if (ArabicCodes.ContainsKey(b))
            {

View on GitHub (pinned to 17a9f07487)

Solutions

  1. Leave Pac.ThrowOnError at its default false to tolerate unmapped bytes (they become empty).
  2. Verify the file is genuinely an Arabic PAC and not a different language track.
  3. Re-export or re-acquire the PAC file if byte corruption is suspected.
  4. If strictness is required, extend the Arabic code map to cover the offending byte.

Example fix

// before (strict)
Pac.ThrowOnError = true;
// after (tolerant, default)
Pac.ThrowOnError = false;
Defensive patterns

Strategy: validation

Validate before calling

// Keep ThrowOnError false (default) so unmapped bytes are skipped, not thrown
Pac.ThrowOnError = false;
new Pac().LoadSubtitle(sub, lines, fileName);
// Set true only for strict one-off audits

Try / catch

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

Prevention

When it happens

Trigger: Decoding a PAC file in Arabic codepage where a byte falls outside the Arabic glyph table and cannot be combined with the following byte into a ligature. ThrowOnError=true converts the silent skip into a hard failure for strict validation.

Common situations: PAC files with embedded non-Arabic glyphs in an Arabic track, mixed-language content, corrupt glyph bytes, or a codepage misclassification (the file is not actually Arabic).

Related errors

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