# CSS: “mask-image”: X is not a “mask-image” value.

> Canonical HTML version: https://rocketvalidator.com/html-validation/css-mask-image-x-is-not-a-mask-image-value
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

The `mask-image` CSS property sets one or more mask layers for an element, controlling which parts are visible based on the mask's alpha channel or luminance. According to the CSS Masking specification, the property accepts a comma-separated list of mask references, where each individual value must be one of:

- **`none`** — No mask layer is applied.
- **A `<image>` value** — This includes `url()` references to image files (PNG, SVG, etc.) and CSS image functions like `image()`.
- **A CSS gradient** — Functions like `linear-gradient()`, `radial-gradient()`, `conic-gradient()`, and their repeating variants (`repeating-linear-gradient()`, etc.).

When the validator encounters a value that doesn't match any of these accepted forms, it flags the error. This matters because browsers will silently discard invalid `mask-image` declarations, meaning your intended masking effect won't apply, and the element will render as if no mask were set.

### Common causes

**Typos in gradient or function names** are a frequent trigger. For example, writing `linear-gradiant()` instead of `linear-gradient()`, or `radial-grad()` instead of `radial-gradient()`.

**Bare image paths without `url()`** will also cause this error. The value `mask.png` is not valid on its own — it must be wrapped as `url('mask.png')`.

**Unsupported keywords or arbitrary strings** like `mask-image: circle` or `mask-image: overlay` are not valid. The only keyword `mask-image` accepts is `none`.

**Malformed gradient syntax** such as missing parentheses, invalid color stops, or incorrect direction keywords can also produce this error. For instance, `linear-gradient(right, red, blue)` is invalid because directional keywords require the `to` prefix.

**Vendor-prefixed values used without the matching prefix on the property** can trigger issues as well. Using `-webkit-gradient()` as a value for the standard `mask-image` property may not validate.

## Examples

### Incorrect: bare image path without `url()`

```html
<div style="mask-image: mask.png;">
  Content here
</div>
```

### Correct: image path wrapped in `url()`

```html
<div style="mask-image: url('mask.png');">
  Content here
</div>
```

### Incorrect: typo in gradient function name

```html
<div style="mask-image: linear-gradiant(to right, transparent, black);">
  Content here
</div>
```

### Correct: properly spelled gradient function

```html
<div style="mask-image: linear-gradient(to right, transparent, black);">
  Content here
</div>
```

### Incorrect: missing `to` keyword in gradient direction

```html
<div style="mask-image: linear-gradient(right, transparent, black);">
  Content here
</div>
```

### Correct: direction uses the `to` keyword

```html
<div style="mask-image: linear-gradient(to right, transparent, black);">
  Content here
</div>
```

### Incorrect: unsupported keyword

```html
<div style="mask-image: overlay;">
  Content here
</div>
```

### Correct: using `none` to explicitly disable masking

```html
<div style="mask-image: none;">
  Content here
</div>
```

### Correct: multiple mask layers

```html
<div style="mask-image: url('star.svg'), linear-gradient(to bottom, black, transparent);">
  Content here
</div>
```

### Correct: radial gradient as a mask

```html
<div style="mask-image: radial-gradient(circle, black 50%, transparent 100%);">
  Content here
</div>
```

Note that browser support for the unprefixed `mask-image` property has improved significantly, but some older browsers may still require the `-webkit-mask-image` prefix. When using the prefixed version, make sure to also include the standard property for forward compatibility. The W3C validator checks against the standard syntax, so always ensure your standard `mask-image` declaration uses valid values even if you also include prefixed versions.