charmbracelet/gum · error

gum version %q is not within given range %q

Error message

gum version %q is not within given range %q

What it means

Both the constraint and current version parsed successfully, but the current gum version does not satisfy the given semver constraint. This is not a crash — it's the command's intended failure result indicating a version requirement check failed.

Source

Thrown at version/command.go:23

	"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

1. Upgrade gum to a version within the required range (e.g. brew upgrade gum, go install latest)
2. Relax the constraint in your check script if the newer version isn't actually needed
3. Verify the installed version with `gum --version`
4. Ensure PATH resolves the intended gum binary (not an old one)

Example fix

// before
gum version --check ">= 0.14.0"   # installed: 0.13.0 → fails
// after
brew upgrade gum && gum version --check ">= 0.14.0"

installed=$(gum --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
required='0.14.0'
lowest=$(printf '%s\n%s\n' "$installed" "$required" | sort -V | head -n1)
[ "$lowest" = "$required" ] || { echo 'gum too old, upgrading'; } 

if ! gum version --check ">= 0.14.0"; then
  echo 'gum is outdated; run: brew upgrade gum' >&2
  exit 1
fi

When it happens

Trigger: Running `gum version --check <constraint>` where c.Check(v) is false, e.g. requiring '>= 0.14.0' while installed gum is 0.13.0.

Common situations: Install scripts verifying minimum gum version before proceeding, CI gate checks for feature availability introduced in a newer gum, stale gum binary on a machine after upgrading scripts.

Related errors

• could not parse range %s: %w
• could not parse version %s: %w
• no options provided, see `gum choose --help`
• nothing selected
• invalid option format: %q

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