SixLabors/ImageSharp · error · ArgumentException

Input string contained non-hexadecimal characters

Error message

Input string contained non-hexadecimal characters

What it means

During the pairwise scan, HexStringToBytes computes byteLo/byteHi via FromHexChar, where invalid characters map to 0xFF; if either nibble is 0xFF the input contained a non-hexadecimal character and an ArgumentException is thrown for the 'chars' parameter.

Solutions

1. Strip non-hex characters (prefixes, spaces, separators) before calling.
2. Pre-validate with a regex/loop over [0-9a-fA-F] and reject bad input with a clearer message.
3. Catch ArgumentException around the call when input origin is untrusted.

Example fix

// before
HexConverter.HexStringToBytes("0xABCD".AsSpan(), dest); // throws
// after
var hex = raw.StartsWith("0x") ? raw[2..] : raw;
hex = hex.Replace(" ", "");
HexConverter.HexStringToBytes(hex.AsSpan(), dest);

static bool IsHexString(ReadOnlySpan<char> s)
{
    foreach (char c in s)
        if (!char.IsAsciiHexDigit(c)) return false;
    return true;
}

static bool IsHexSafe(ReadOnlySpan<char> s) =>
    s.Length % 2 == 0 && !s.ContainsAnyInRange('g', 'z') && s.IndexOfAny(" _-0x") < 0;

try { written = HexConverter.HexStringToBytes(hex.AsSpan(), dest); }
catch (ArgumentException) { ReportInvalidHex(hex); }

When it happens

Trigger: Hex strings containing 'g'-'z', whitespace, '0x' prefixes, or other non-[0-9a-fA-F] characters, e.g. HexStringToBytes("0xAB".AsSpan(), dest).

Common situations: Copying hex values including a "0x" prefix; strings with embedded spaces or separators; uppercase/lowercase confusion is fine but punctuation is not; decoding data that was corrupted in transit.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Input string length must be a multiple of 2
• Output span must be at least half the length of the input…
• Input string is not in the correct format.
• Unsupported color hex format.
• The BigTIFF directory entry count exceeds the available…

AI-assisted analysis of SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/2ff7a6b13776eca2. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Common/Helpers/HexConverter.cs:89

            // byteHi hasn't been shifted to the high half yet, so the only way the bitwise or produces this pattern
            // is if either byteHi or byteLo was not a hex character.
            if ((byteLo | byteHi) == 0xFF)
            {
                break;
            }

            bytes[j++] = (byte)((byteHi << 4) | byteLo);
            i += 2;
        }

        if (byteLo == 0xFF)
        {
            i++;
        }

        if ((byteLo | byteHi) == 0xFF)
        {
            throw new ArgumentException("Input string contained non-hexadecimal characters", nameof(chars));
        }

        return j;
    }
}

View on GitHub (pinned to 59ce6af6fc)