# CSS: “border-width”: X is not a “border-width” value.

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

The `border-width` property controls the thickness of an element's border. According to the CSS specification, its accepted values fall into two categories:

- **Length values** — any valid CSS length such as `1px`, `0.25em`, `2rem`, `3pt`, or `0.1cm`. The value must not be negative.
- **Keywords** — exactly three are defined: `thin`, `medium`, and `thick`. These map to implementation-defined sizes but are guaranteed to maintain the relationship `thin ≤ medium ≤ thick`.

A bare number like `5` (without a unit) is not valid, even though some browsers may silently accept it. Similarly, words like `large`, `bold`, `normal`, or color values like `red` are not valid `border-width` values. Percentage values (e.g., `10%`) are also not accepted for `border-width`, unlike many other CSS properties that accept lengths.

This matters for several reasons. First, invalid CSS values cause the declaration to be ignored entirely, meaning the border may not render as intended — or may fall back to the initial value of `medium`, producing unexpected results. Second, relying on browser error-recovery behavior leads to inconsistent rendering across different browsers and versions. Third, valid CSS ensures your stylesheets are maintainable and predictable.

Common causes of this error include:

- **Missing units** — writing `border-width: 2` instead of `border-width: 2px`. The only unitless length allowed in CSS is `0`.
- **Misspelled or invented keywords** — using `large`, `small`, `normal`, or `none` instead of `thin`, `medium`, or `thick`.
- **Wrong value type** — accidentally using a color name, percentage, or other non-length value.
- **Typos in units** — writing `5xp` instead of `5px`.

To fix the issue, locate the offending `border-width` declaration and replace the invalid value with a proper CSS length (including its unit) or one of the three accepted keywords.

## Examples

### Invalid: using a non-existent keyword

```html
<style>
  .box {
    border-style: solid;
    border-width: large; /* "large" is not a valid border-width value */
  }
</style>
<div class="box">Content</div>
```

### Fixed: using a valid keyword

```html
<style>
  .box {
    border-style: solid;
    border-width: thick;
  }
</style>
<div class="box">Content</div>
```

### Invalid: missing unit on a number

```html
<style>
  .alert {
    border: solid;
    border-width: 3; /* unitless number is not valid */
  }
</style>
<div class="alert">Warning</div>
```

### Fixed: adding a proper unit

```html
<style>
  .alert {
    border: solid;
    border-width: 3px;
  }
</style>
<div class="alert">Warning</div>
```

### Invalid: using a percentage

```html
<style>
  .panel {
    border-style: solid;
    border-width: 5%; /* percentages are not valid for border-width */
  }
</style>
<div class="panel">Panel</div>
```

### Fixed: using a length value instead

```html
<style>
  .panel {
    border-style: solid;
    border-width: 0.3em;
  }
</style>
<div class="panel">Panel</div>
```

### Using multiple values with shorthand

The `border-width` property accepts one to four values (for top, right, bottom, left), and each must independently be valid:

```html
<style>
  .card {
    border-style: solid;
    border-width: thin 2px medium 1px;
  }
</style>
<div class="card">Card content</div>
```

Replace any invalid `border-width` value with a recognized CSS length (always including the unit, except for `0`) or one of the keywords `thin`, `medium`, or `thick` to resolve the validation error.