Textualize/textual · error · ScalarResolveError

expected dimensions; found {str(self)!r}

Error message

expected dimensions; found {str(self)!r}

What it means

Raised by Scalar.resolve when the scalar's unit has no entry in RESOLVE_MAP, i.e. the unit cannot be resolved to a dimension in the current context (typically a percent/relative unit resolved without a reference size).

Source

Thrown at src/textual/css/scalar.py:291

            size: Size of the container.
            viewport: Size of the viewport (typically terminal size)

        Raises:
            ScalarResolveError: If the unit is unknown.

        Returns:
            A size (in cells)
        """
        value, unit, percent_unit = self

        if unit == Unit.PERCENT:
            unit = percent_unit
        try:
            dimension = RESOLVE_MAP[unit](
                value, size, viewport, fraction_unit or _FRACTION_ONE
            )
        except KeyError:
            raise ScalarResolveError(f"expected dimensions; found {str(self)!r}")
        return dimension

    def copy_with(
        self,
        value: float | None = None,
        unit: Unit | None = None,
        percent_unit: Unit | None = None,
    ) -> Scalar:
        """Get a copy of this Scalar, with values optionally modified

        Args:
            value: The new value, or None to keep the same value
            unit: The new unit, or None to keep the same unit
            percent_unit: The new percent_unit, or None to keep the same percent_unit
        """
        return Scalar(
            value if value is not None else self.value,
            unit if unit is not None else self.unit,

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Construct scalars via Scalar.parse or Scalar.from_number instead of manual unit combos
2. Ensure you pass a concrete size when resolving percent-based scalars
3. Check that unit and percent_unit arguments are compatible (both dimensionful or both fractional)

Example fix

// before
scalar = Scalar(50.0, Unit.PERCENT, Unit.PERCENT)
scalar.resolve(None, viewport)
// after
scalar = Scalar(50.0, Unit.PERCENT, Unit.CELLS)
scalar.resolve(container_width, viewport)

from textual.css.scalar import Scalar
def resolvable(scalar: Scalar) -> bool:
    from textual.css.scalar import RESOLVE_MAP
    return scalar.unit in RESOLVE_MAP

from textual.css.scalar import ScalarResolveError
try:
    dim = scalar.resolve(size, viewport)
except ScalarResolveError:
    dim = scalar.resolve(size, viewport, percent_unit=Unit.CELLS)

When it happens

Trigger: Calling scalar.resolve(size, viewport, fraction_unit) where scalar has a unit (e.g. Unit.PERCENT as percent_unit) but the corresponding resolver is missing from RESOLVE_MAP — commonly resolving a scalar that was constructed with mismatched units, or resolving CELLS/percent units without proper dimension context.

Common situations: Manually constructing Scalar objects with inconsistent unit/percent_unit arguments; resolving a scalar captured from a different layout context; version changes that add new units not present in RESOLVE_MAP.

Related errors

• {token!r} is not a valid scalar
• Expected a str, Path or list[str | Path] for the CSS_PATH.
• {self.name} must be one of {friendly_list(self._valid_values
• {self.name} must be a str
• invalid percentage value '{token}'

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/30d05893931cc7de. Report an issue: GitHub.