bchavez/Bogus · error · ArgumentException

alphabet must contain at least 4 unique characters.

Error message

alphabet must contain at least 4 unique characters.

What it means

Thrown by the Hashids constructor when the deduplicated alphabet contains fewer than 16 characters. Note: the message text says 'at least 4 unique characters' but the actual guard is MIN_ALPHABET_LENGTH (16); this is a known message/code mismatch. The deduplication (alphabet.Distinct()) happens before the check, so duplicate characters count only once.

Source

Thrown at Source/Bogus/Hashids.cs:56

   /// <summary>
   /// Instantiates a new Hashids en/de-coder.
   /// </summary>
   /// <param name="salt"></param>
   /// <param name="minHashLength"></param>
   /// <param name="alphabet"></param>
   public Hashids(string salt = "", int minHashLength = 0, string alphabet = DEFAULT_ALPHABET, string seps = DEFAULT_SEPS)
   {
      if( string.IsNullOrWhiteSpace(alphabet) )
         throw new ArgumentNullException("alphabet");

      this.salt = salt;
      this.alphabet = string.Concat(alphabet.Distinct());
      this.seps = seps;
      this.minHashLength = minHashLength;

      if( this.alphabet.Length < 16 )
         throw new ArgumentException("alphabet must contain at least 4 unique characters.", "alphabet");

      this.SetupSeps();
      this.SetupGuards();
   }

   /// <summary>
   /// Encodes the provided numbers into a hashed string
   /// </summary>
   /// <param name="numbers">the numbers to encode</param>
   /// <returns>the hashed string</returns>
   public virtual string Encode(params int[] numbers)
   {
      return this.GenerateHashFrom(numbers.Select(n => (long)n).ToArray());
   }

   /// <summary>
   /// Encodes the provided numbers into a hashed string
   /// </summary>

View on GitHub (pinned to 6ece18c5c2)

Solutions

Supply an alphabet with at least 16 unique characters (the default DEFAULT_ALPHABET has 62).
Remove duplicate characters from your custom alphabet and recount the unique set.
If a short alphabet is mandatory, fork or wrap Hashids since the 16-char minimum is hardcoded.

Example fix

// before
var h = new Hashids("salt", 0, "abcd1234");
// after
var h = new Hashids("salt", 0, Hashids.DEFAULT_ALPHABET);

Defensive patterns

Strategy: validation

Validate before calling

static Hashids MakeHashids(string salt, string alphabet) {
    var unique = alphabet.Distinct().Count();
    if (unique < 16) throw new InvalidOperationException($"alphabet has {unique} unique chars; need >=16");
    return new Hashids(salt, 0, alphabet);
}

Try / catch

try { return new Hashids(salt, 0, alphabet); }
catch (ArgumentException ex) when (ex.Message.Contains("alphabet")) {
    // fall back to default alphabet
    return new Hashids(salt);
}

Prevention

Default to Hashids.DEFAULT_ALPHABET unless a custom one is required.
Count unique chars before constructing.
Document the 16-char minimum at every config site.

When it happens

Trigger: Constructing new Hashids(alphabet: "abc") or any custom alphabet whose Distinct() result is shorter than 16 characters. Also triggered by passing a long string with many repeated characters that collapses to <16 unique ones.

Common situations: Customizing the Hashids alphabet with a short or repetitive character set; migrating from another hashid library with a smaller alphabet.

Related errors

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