tailwindlabs/tailwindcss · error · Error

The --spacing(…) function requires that the `--spacing` them

Error message

The --spacing(…) function requires that the `--spacing` theme variable exists, but it was not found.

What it means

Thrown by the `--spacing(...)` handler after argument validation succeeds but the theme lookup `designSystem.theme.resolve(null, ['--spacing'])` returns a falsy value. The `--spacing` base variable is the engine of all spacing utilities (`p-*`, `m-*`, `gap-*`, etc.); if it is absent the multiplier cannot be computed. This typically means the default theme was removed or overridden without redefining `--spacing`.

Source

Thrown at packages/tailwindcss/src/css-functions.ts:61

function spacing(
  designSystem: DesignSystem,
  _source: AstNode,
  value: string,
  ...rest: string[]
): string {
  if (!value) {
    throw new Error(`The --spacing(…) function requires an argument, but received none.`)
  }

  if (rest.length > 0) {
    throw new Error(
      `The --spacing(…) function only accepts a single argument, but received ${rest.length + 1}.`,
    )
  }

  let multiplier = designSystem.theme.resolve(null, ['--spacing'])
  if (!multiplier) {
    throw new Error(
      'The --spacing(…) function requires that the `--spacing` theme variable exists, but it was not found.',
    )
  }

  // Optimization:
  //
  // - We know that at this point the `--spacing` value must be set.
  // - We know that `--spacing` must be set to a `<length>` unit, such as `0.25rem`
  // - We can assume that the `--spacing` value is not set to a `0`-like value.
  //   Otherwise `p-<anything>` would calculate as `0` which wouldn't make sense.
  //
  // - That means that a value of `0` can be replaced by `0px`. It's important
  //   to keep the unit so the value stays a `<length>`, e.g. when assigned to
  //   a custom property and later used inside `calc(…)`.
  // - That means that a value of `1` can be replaced by `multiplier`
  let valueDimension = dimensions.get(value)
  if (valueDimension) {
    if (valueDimension[0] === 0) return '0px'

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Define `--spacing` in your `@theme` block, e.g. `@theme { --spacing: 0.25rem; }`.
2. If you used `--spacing: initial` to clear it, re-add a concrete length afterward.
3. Ensure the default `theme.css` (which ships `--spacing: 0.25rem`) is still imported by your entry CSS.
4. Avoid calling `--spacing(...)` directly in custom CSS if your theme intentionally omits the variable; use explicit lengths instead.

Example fix

/* before */
@theme {
  --spacing: initial;
}
.x { padding: --spacing(4); }
/* after */
@theme {
  --spacing: 0.25rem;
}
.x { padding: --spacing(4); }

// Ensure the --spacing variable is defined in the theme before using --spacing()
function ensureSpacingTheme(themeCss: string): boolean {
  return /--spacing\s*:/.test(themeCss);
}
if (!ensureSpacingTheme(myTheme)) {
  throw new Error('Add `--spacing: 0.25rem;` to your @theme block');
}

When it happens

Trigger: A `@theme` block that clears defaults (e.g. `--spacing: initial;`) without redefining `--spacing`; disabling the default theme import; a custom design system built without the spacing scale; calling `--spacing(4)` in a context where the theme was built in reference-only mode missing the variable.

Common situations: Replacing Tailwind's default theme wholesale and forgetting `--spacing`; using `@theme reference` only; upgrading a config that previously relied on `theme.spacing` being implicitly present.

Related errors

• The --spacing(…) function requires an argument, but received
• The --alpha(…) function requires a color and an alpha value,
• The --spacing(…) function only accepts a single argument, bu
• The --theme(…) function can only be used with CSS variables
• Could not resolve value for theme function: `theme(${path})`

AI-assisted analysis of tailwindlabs/tailwindcss@16e94cbf7f (2026-08-12). Data as JSON: /api/errors/632dc5927c387563. Report an issue: GitHub.