What causes "could not parse range %s: %w" in charmbracelet/gum?

Use valid semver constraint syntax, e.g. --check '>= 0.14.0'

could not parse range %s: %w

Error message

could not parse range %s: %w

What it means

`gum version --check` could not parse the provided --constraint string as a valid semantic version constraint (Masterminds/semver). The constraint must be an expression like '>= 1.2.0' or '~1.0'. The parse error is wrapped with %w.

Source

Thrown at version/command.go:15

// Package version the version command.
package version

import (
	"fmt"

	"github.com/Masterminds/semver/v3"
	"github.com/alecthomas/kong"
)

// Run check that a given version matches a semantic version constraint.
func (o Options) Run(ctx *kong.Context) error {
	c, err := semver.NewConstraint(o.Constraint)
	if err != nil {
		return fmt.Errorf("could not parse range %s: %w", o.Constraint, err)
	}
	current := ctx.Model.Vars()["versionNumber"]
	v, err := semver.NewVersion(current)
	if err != nil {
		return fmt.Errorf("could not parse version %s: %w", current, err)
	}
	if !c.Check(v) {
		return fmt.Errorf("gum version %q is not within given range %q", current, o.Constraint)
	}
	return nil
}

View on GitHub (pinned to 4d089f9550)

Solutions

Use valid semver constraint syntax, e.g. --check '>= 0.14.0'
Quote the constraint in the shell so '>' isn't interpreted as redirection
Verify the constraint variable is non-empty in scripts
Check Masterminds/semver docs for supported constraint operators

Example fix

// before
gum version --check > 1.0.0     # shell treats '>' as redirect
// after
gum version --check ">= 1.0.0"

Defensive patterns

Strategy: validation

Validate before calling

constraint='>= 0.14.0'
[[ "$constraint" =~ ^[><=~![:space:]]*[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "bad constraint: $constraint" >&2; exit 1; }

Try / catch

if ! gum version --check "$constraint" 2>err.txt; then
  grep -q 'could not parse range' err.txt && echo 'fix constraint syntax' >&2
fi

Prevention

Always quote constraints in shell to protect > and <
Use documented semver operators (>=, <=, ~, ^, =)
Validate constraint variables are non-empty before use

When it happens

Trigger: Running `gum version --check` with a constraint string semver.NewConstraint rejects — typos, empty string, or unsupported syntax like 'v1.x' wildcards or bare ranges.

Common situations: Typing 'greater than 1.0' instead of '>= 1.0.0', passing shell-unescaped '>' that the shell mangles, empty constraint variable in a script, using prerelease notation incorrectly.

Related errors

AI-assisted analysis of charmbracelet/gum@4d089f9550 (2026-08-31). Data as JSON: /api/errors/a05ff97fd0a97148. Report an issue: GitHub.