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

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

<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

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

Invalid: missing unit on a number

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

Fixed: adding a proper unit

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

Invalid: using a percentage

<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

<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:

<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.

Learn more:

MDN Reference

MDN Web Docs: border-width

→

MDN Reference

MDN Web Docs: border property

→