hasura/graphql-engine · error

cannot update from a non-semver version: %s

Error message

cannot update from a non-semver version: %s

What it means

The update command requires a valid semver CLI version to compare against available releases. o.EC.Version.CLISemver is nil (the version string couldn't be parsed as semver), so the update check is aborted. This typically happens with dev builds where the version is not a semantic version.

Source

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

	f.StringVar(&opts.version, "version", "", "a specific version to install")

	return updateCmd
}

type updateOptions struct {
	EC *cli.ExecutionContext

	version string
}

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()

View on GitHub (pinned to 724551b9ae)

Solutions

1. If built from source, rebuild embedding a proper semver, e.g. `go build -ldflags "-X github.com/hasura/graphql/cli/version.BuildVersion=v2.30.0"`
2. Or install an official release binary (curl the install script / release asset) and re-run update-cli
3. Check `hasura version` output — if it isn't a clean vX.Y.Z, that's the cause

Example fix

# before
$ go build ./cmd/hasura && ./hasura update-cli
# after
$ go build -ldflags "-X github.com/hasura/graphql/cli/version.BuildVersion=v2.30.0" ./cmd/hasura && ./hasura update-cli

// verify the CLI reports a parseable semver before updating
out, _ := exec.Command("hasura", "version").Output()
v, err := semver.NewVersion(strings.TrimSpace(strings.Fields(string(out))[0]))
if err != nil || v == nil {
    log.Fatal("CLI version is not semver; install an official release before updating")
}

func canSelfUpdate(versionStr string) bool {
    v, err := semver.NewVersion(versionStr)
    return err == nil && v != nil
}

When it happens

Trigger: Running `hasura update-cli` on a binary built with a non-semver version string (e.g. 'dev', 'dirty', a git SHA, or an empty version), which makes semver parsing of CLIVersion fail and leaves CLISemver nil.

Common situations: Building the CLI from source without version ldflags, installing via a fork, or a corrupted install where the embedded version string is malformed.

Related errors

• unable to parse version: %w
• 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/f16947f597334cfb. Report an issue: GitHub.