What causes "Variant must not be higher than 63." in thebookisclosed/ViVe?

Clamp or validate the variant to 0-63 before assignment

thebookisclosed/ViVe · error · FeaturePropertyOverflowException

Variant must not be higher than 63.

Error message

Variant must not be higher than 63.

What it means

Variant in RTL_FEATURE_CONFIGURATION occupies bits 8-13 of CompactState (6 bits), so its maximum value is 63. Assigning a larger value would overwrite VariantPayloadKind bits, so the setter throws FeaturePropertyOverflowException("Variant", 63).

Solutions

Clamp or validate the variant to 0-63 before assignment
Mask the source value: variant & 0x3F
Verify the variant actually exists for the feature — values above 63 are never valid in this ABI

Example fix

// before
config.Variant = importedVariant; // may exceed 63
// after
config.Variant = importedVariant & 0x3F; // or validate: if (importedVariant > 63) throw ...

Defensive patterns

Strategy: validation

Validate before calling

if (variant > 63) throw new ArgumentOutOfRangeException(nameof(variant), "Variant must be 0-63.");
config.Variant = variant;

Type guard

static bool IsValidVariant(uint v) => v <= 63;

Try / catch

try { config.Variant = variant; }
catch (FeaturePropertyOverflowException ex)
{
    // reject or clamp: ex names Variant with max 63
}

Prevention

Validate external variant inputs against the 0-63 bound
Remember the packed field is 6 bits — nothing larger can round-trip
When importing variants, verify the feature actually defines that variant

When it happens

Trigger: Setting config.Variant to any uint greater than 63, e.g. copying a variant value from an unconstrained source such as a config file or API response.

Common situations: Hand-editing variant numbers from documentation or another tool that uses wider variant fields; bulk-applying variant experiments whose IDs exceed the 6-bit Windows feature-variant range.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of thebookisclosed/ViVe@3f8c6a3425 (2026-09-14). Data as JSON: /api/errors/5e1f34e3463f06a0. Report an issue: GitHub.

Appendix: source

Thrown at ViVe/NativeStructs.cs:101

            {
                return ((CompactState & 0x80) >> 7) == 1;
            }
            set
            {
                CompactState = (CompactState & 0xFFFFFF7F) | ((value ? (uint)1 : 0) << 7);
            }
        }

        public uint Variant
        {
            get
            {
                return (CompactState & 0x3F00) >> 8;
            }
            set
            {
                if (value > 63)
                    throw new FeaturePropertyOverflowException("Variant", 63);
                CompactState = (CompactState & 0xFFFFC0FF) | (value << 8);
            }
        }

        public RTL_FEATURE_VARIANT_PAYLOAD_KIND VariantPayloadKind
        {
            get
            {
                return (RTL_FEATURE_VARIANT_PAYLOAD_KIND)((CompactState & 0xC000) >> 14);
            }
            set
            {
                if ((uint)value > 3)
                    throw new FeaturePropertyOverflowException("VariantPayloadKind", 3);
                CompactState = (CompactState & 0xFFFF3FFF) | ((uint)value << 14);
            }
        }
    }

View on GitHub (pinned to 3f8c6a3425)