hasura/graphql-engine · error

unable to parse version: %w

Error message

unable to parse version: %w

What it means

Thrown when an explicit version string passed to `hasura update-cli --version <v>` cannot be parsed by semver.NewVersion. The CLI accepts an optional pin version; it must be valid semver (with optional v prefix).

Source

Thrown at cli/commands/update-cli.go:89

}

func (o *updateOptions) run(showPrompt bool) (err error) {
	var op errors.Op = "commands.updateOptions.run"

	currentVersion := o.EC.Version.CLISemver
	if currentVersion == nil {
		return errors.E(
			op,
			fmt.Errorf("cannot update from a non-semver version: %s", o.EC.Version.GetCLIVersion()),
		)
	}

	var versionToBeInstalled *semver.Version
	if o.version != "" {
		// parse the version
		versionToBeInstalled, err = semver.NewVersion(o.version)
		if err != nil {
			return errors.E(op, fmt.Errorf("unable to parse version: %w", err))
		}
	} else {
		o.EC.Spin("Checking for update... ")
		hasUpdate, latestVersion, hasPreReleaseUpdate, preReleaseVersion, err := update.HasUpdate(
			currentVersion,
			o.EC.LastUpdateCheckFile,
		)
		o.EC.Spinner.Stop()

		if err != nil {
			return errors.E(op, fmt.Errorf("command: check update: %w", err))
		}

		ec.Logger.Debugln(
			"hasUpdate: ",
			hasUpdate,
			"latestVersion: ",
			latestVersion,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Use a full release tag from GitHub releases, e.g. `hasura update-cli --version v2.30.0`
2. Omit --version entirely to update to the latest stable release

Example fix

# before
hasura update-cli --version latest
# after
hasura update-cli  # or: hasura update-cli --version v2.30.0

// validate the pin version before passing it to update-cli
if _, err := semver.NewVersion(flagVersion); flagVersion != "" && err != nil {
    log.Fatalf("--version must be valid semver, e.g. v2.30.0 (got %q)", flagVersion)
}

func isValidSemver(s string) bool {
    _, err := semver.NewVersion(s)
    return err == nil
}

When it happens

Trigger: `hasura update-cli --version v1.0` (missing patch), `--version 2.x`, `--version latest`, or any non-semver string.

Common situations: Users assuming `--version latest` works, copying a branch name or partial tag instead of a release tag, missing 'v' is fine but malformed numbers are not.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• cannot update from a non-semver version: %s
• command: check update: %w
• apply update: %w
• error serving console: %w
• operation failed: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/5ecab750fd9e504b. Report an issue: GitHub.