bchavez/Bogus · error · ArgumentOutOfRangeException

.{nameof(OrNull)}() {nameof(nullWeight)} of '{nullWeight}' m

Error message

.{nameof(OrNull)}() {nameof(nullWeight)} of '{nullWeight}' must be between 1.0f and 0.0f.

What it means

OrNull<T>(this T value, in Faker f, float nullWeight) for reference types throws ArgumentOutOfRangeException if nullWeight is below 0 or above 1. nullWeight is the probability of returning null, so it must lie in [0.0, 1.0]. Default is 0.5.

Source

Thrown at Source/Bogus/Faker[T].Extensions.cs:35

   /// <param name="max">Maximum number of T objects to create. Inclusive.</param>
   public static List<T> GenerateBetween<T>(this Faker<T> faker, int min, int max, string ruleSets = null) where T : class
   {
      var internals = (IFakerTInternal)faker;
      var r = internals.FakerHub.Random;
      var n = r.Number(min, max);
      return faker.Generate(n, ruleSets);
   }

   /// <summary>
   /// Helpful extension for creating randomly null values for <seealso cref="Faker{T}"/>.RuleFor() rules.
   /// Example: .RuleFor(x=>x.Prop, f=>f.Random.Word().OrNull(f))
   /// </summary>
   /// <typeparam name="T">Any reference type.</typeparam>
   /// <param name="f">The Faker facade. This is usually the f from RuleFor(.., f => lambda).</param>
   /// <param name="nullWeight">The probability of null occurring. Range [1.0f - 0.0f] (100% and 0%) respectively. For example, if 15% null is desired pass nullWeight = 0.15f.</param>
   public static T OrNull<T>(this T value, in Faker f, float nullWeight = 0.5f) where T : class
   {
      if (nullWeight is > 1 or < 0) throw new ArgumentOutOfRangeException(nameof(nullWeight), $".{nameof(OrNull)}() {nameof(nullWeight)} of '{nullWeight}' must be between 1.0f and 0.0f.");
      return f.Random.Float() > nullWeight ? value : null;
   }

   /// <summary>
   /// Helpful extension for creating randomly null values for <seealso cref="Faker{T}"/>.RuleFor() rules.
   /// Example: .RuleFor(x=>x.Prop, f=>f.Random.Int().OrNull(f))
   /// </summary>
   /// <typeparam name="T">Any nullable type. ie: int?, Guid?, etc.</typeparam>
   /// <param name="f">The Faker facade. This is usually the f from RuleFor(.., f => lambda).</param>
   /// <param name="nullWeight">The probability of null occurring. Range [1.0f - 0.0f] (100% and 0%) respectively. For example, if 15% null is desired pass nullWeight = 0.15f.</param>
   public static T? OrNull<T>(this T value, Faker f, float nullWeight = 0.5f) where T : struct
   {
      if (nullWeight is > 1 or < 0) throw new ArgumentOutOfRangeException(nameof(nullWeight), $".{nameof(OrNull)}() {nameof(nullWeight)} of '{nullWeight}' must be between 1.0f and 0.0f.");
      return f.Random.Float() > nullWeight ? new T?(value) : null;
   }

   /// <summary>
   /// Helpful extension for creating randomly default(T) values for <seealso cref="Faker{T}"/>.RuleFor() rules.

View on GitHub (pinned to 6ece18c5c2)

Solutions

Pass a fraction in [0.0, 1.0]; for 15% null use 0.15f.
Clamp the weight before calling: Math.Clamp(weight, 0f, 1f).
Omit the argument to use the 0.5 default.

Example fix

// before
.RuleFor(x => x.Name, f => f.Name.FullName().OrNull(f, 15f))

// after
.RuleFor(x => x.Name, f => f.Name.FullName().OrNull(f, 0.15f))

Defensive patterns

Strategy: validation

Validate before calling

float nullWeight = Math.Clamp(rawWeight, 0f, 1f);
var v = f.Random.Word().OrNull(f, nullWeight);

Type guard

static bool IsValidWeight(float w) => w >= 0f && w <= 1f;

Prevention

Pass a fraction (0.15), not a percent (15).
Clamp externally supplied weights to [0,1].
Omit nullWeight to use the 0.5 default.

When it happens

Trigger: Calling f.Random.Word().OrNull(f, 1.5f) or .OrNull(f, -0.2f) on a reference-type value in a RuleFor lambda.

Common situations: Passing a percentage (e.g. 15) instead of a fraction (0.15); passing a computed weight that under/overflows the [0,1] band.

Related errors

AI-assisted analysis of bchavez/Bogus@6ece18c5c2 (2026-08-13). Data as JSON: /api/errors/833a6efa77b39cc1. Report an issue: GitHub.