subframe7536/maple-font · error · ValueError

Original reference width must be positive

Error message

Original reference width must be positive

What it means

smart_change_width() scales all glyph advances horizontally by target_width/original_ref_width. The reference width is the denominator of the scale factor, so it must be positive; if original_ref_width <= 0 the function raises this ValueError before modifying the font.

Source

Thrown at source/py/transform.py:229

        final_lsb = new_lsb

    hmtx[glyph_name] = (new_width, final_lsb)


def smart_change_width(
    font: TTFont,
    target_width: int,
    original_ref_width: int,
    also_scale_y: bool = False,
) -> None:
    """
    Global font resizer. Scales all glyphs horizontally and applies
    smart thickening to counteract the "squashed" look.

    For non-CN glyphs in the build process.
    """
    if original_ref_width <= 0:
        raise ValueError("Original reference width must be positive")

    font["hhea"].advanceWidthMax = target_width  # type: ignore
    hmtx: Any = font["hmtx"]
    glyf: Any = font["glyf"]

    scale_factor = target_width / original_ref_width
    composites: list[str] = []

    for glyph_name in font.getGlyphOrder():
        _change_glyph_width(
            glyf=glyf,
            hmtx=hmtx,
            glyph_name=glyph_name,
            scale_x=scale_factor,
            scale_y=scale_factor if also_scale_y else 1.0,
            match_width=original_ref_width,
            target_width=target_width,
        )

View on GitHub (pinned to c08fda97fe)

Solutions

1. Check the input font's advance widths (hmtx/hhea.advanceWidthMax) — use a valid font with positive advances.
2. In calling code, validate/clamp original_ref_width > 0 (fall back to a sane default like the font's unitsPerEm) before invoking.
3. If the width is auto-computed, fix the computation so it averages only glyphs with nonzero advances.

Example fix

// before
smart_change_width(font, 1000, original_ref_width)

// after
ref = original_ref_width if original_ref_width > 0 else font["head"].unitsPerEm
smart_change_width(font, 1000, ref)

ref = font["hhea"].advanceWidthMax or font["head"].unitsPerEm
assert ref > 0, f"reference width must be positive, got {ref}"

def has_positive_ref_width(ref: float) -> bool:
    return isinstance(ref, (int, float)) and ref > 0

try:
    smart_change_width(font, target_width, original_ref_width)
except ValueError as e:
    if "reference width" in str(e):
        smart_change_width(font, target_width, font["head"].unitsPerEm)
    else:
        raise

When it happens

Trigger: Calling smart_change_width (via build_nf_by_prebuild_nerd_font or build_variable_fonts) with original_ref_width of 0, a negative number, or a width read from an uninitialized/empty font metric (e.g. xHea/advanceWidthMax == 0 or a computed average over zero glyphs).

Common situations: Broken or stub font lacking real advance widths (hmtx all zeros); a pre-build Nerd Font whose measured reference width is 0; passing width_scale config mistake propagating as an invalid reference; division-by-zero guard doing its job.

Related errors

• Glyph '{glyph_name}' not found in font.
• Font does not have an OS/2 table.
• This script only supports TrueType (glyf) fonts. CFF support
• No hhea table found.
• No OS/2 table found.

AI-assisted analysis of subframe7536/maple-font@c08fda97fe (2026-08-28). Data as JSON: /api/errors/0ef2db59cd64457d. Report an issue: GitHub.