CSS: “mask”: Too many values or values are not recognized.

The mask CSS shorthand property allows you to hide parts of an element by masking or clipping it at specific points. It combines several longhand properties into one declaration: mask-image, mask-mode, mask-repeat, mask-position, mask-clip, mask-origin, mask-size, and mask-composite.

Because mask is a shorthand that accepts values for many sub-properties, it’s easy to trigger validation errors. Common causes include:

• Too many values: Providing more values than the shorthand grammar allows, or duplicating values for the same sub-property.
• Unrecognized values: Using vendor-specific values (like -webkit- prefixed keywords), typos, or values that belong to a different CSS property.
• Incorrect value order: The shorthand has a specific grammar. For example, mask-size values must follow mask-position values and be separated by a /, similar to the background shorthand.
• Mixing shorthand and longhand concepts: Trying to set values that aren’t part of the mask shorthand grammar.

The formal syntax for a single mask layer is:

<mask-layer> = <mask-reference> || <position> [ / <bg-size> ]? || <repeat-style> ||
               <geometry-box> || [ <geometry-box> | no-clip ] || <compositing-operator> ||
               <masking-mode>

This is a problem for standards compliance because invalid CSS can lead to the entire declaration being ignored by browsers, causing your masking effect to silently fail. It also affects cross-browser compatibility — different browsers have varying levels of support for the mask shorthand, and using individual longhand properties is often more reliable.

To fix this issue:

1. Check each value in your mask declaration and ensure it’s a valid value for one of the mask sub-properties.
2. Use longhand properties instead of the shorthand if you only need to set one or two aspects of the mask. This avoids ambiguity and improves readability.
3. Separate position and size with / if you’re specifying both, e.g., center / contain.
4. Remove or separate vendor prefixes — use -webkit-mask for WebKit-specific syntax and the standard mask for standards-compliant syntax, but don’t mix prefixed values into the unprefixed property.

Examples

Incorrect: too many or unrecognized values in the shorthand

<style>
  .masked {
    /* Error: too many values / unrecognized combination */
    mask: url(mask.svg) center center no-repeat contain;
  }
</style>
<div class="masked">Content</div>

Here, contain is a mask-size value but it must be separated from the position with a /. Without the slash, the validator sees an extra unrecognized value.

Correct: proper shorthand syntax with position and size

<style>
  .masked {
    mask: url(mask.svg) center / contain no-repeat;
  }
</style>
<div class="masked">Content</div>

The / separates mask-position (center) from mask-size (contain), just like in the background shorthand.

Correct: using longhand properties for clarity and compatibility

<style>
  .masked {
    width: 100px;
    height: 100px;
    background-color: #8cffb0;
    -webkit-mask-image: url(sun.svg);
    mask-image: url(sun.svg);
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: contain;
  }
</style>
<div class="masked">Content</div>

Using individual longhand properties avoids shorthand parsing issues entirely. Including the -webkit-mask-image prefix alongside the standard mask-image ensures broader browser support.

Incorrect: unrecognized value in the shorthand

<style>
  .masked {
    /* "luminance" is a mask-mode value but may not be recognized in the shorthand by all validators */
    mask: url(mask.png) luminance;
  }
</style>
<div class="masked">Content</div>

Correct: using the longhand for mask mode

<style>
  .masked {
    mask-image: url(mask.png);
    mask-mode: luminance;
  }
</style>
<div class="masked">Content</div>

When in doubt, splitting the mask shorthand into its individual longhand properties is the safest approach. It makes your intent explicit, avoids validation errors, and tends to have better cross-browser support.

Más información:

MDN Reference

MDN - CSS mask

→

MDN Reference

MDN - CSS mask-image

→