dgraph-io/dgraph · error

version can't be empty and must start with `v`. E.g.: v1.2.2

Error message

version can't be empty and must start with `v`. E.g.: v1.2.2

What it means

parseVersionFromString requires a non-empty version string that starts with a literal 'v'. This error is returned when the value is empty (e.g. missing flag value or empty env/config) or lacks the v prefix, so it cannot be a valid Dgraph version tag.

Source

Thrown at upgrade/upgrade.go:219

func formatAsFlagParsingError(flag string, err error) error {
	return fmt.Errorf("error parsing flag `%s`: %w", flag, err)
}

// parseVersionFromString parses a version given as string to internal representation.
// Some examples for input and output:
//  1. input : v1.2.2
//     output: &version{major: 1, minor: 2, patch: 2}, nil
//  2. input : v20.03.0-beta.20200320
//     output: &version{major: 20, minor: 3, patch: 0}, nil
//  3. input : 1.2.2
//     output: nil, error
//  4. input : v1.2.2s
//     output: nil, error
func parseVersionFromString(v string) (*version, error) {
	v = strings.TrimSpace(v)
	if v == "" || v[:1] != "v" {
		return nil, fmt.Errorf("version can't be empty and must start with `v`. E.g.: v1.2.2")
	}

	versionSplit := strings.Split(v[1:], ".")
	result := &version{}
	var err error

	result.major, err = strconv.Atoi(versionSplit[0])
	if err != nil {
		return nil, fmt.Errorf("error parsing major version: %w", err)
	}

	result.minor, err = strconv.Atoi(versionSplit[1])
	if err != nil {
		return nil, fmt.Errorf("error parsing minor version: %w", err)
	}

	// the third part of split might contain some extra things like `beta` appended with -,
	// so split again and take the first part as patch

View on GitHub (pinned to 759e242be6)

Solutions

1. Set the flag/config value to a full tag with the v prefix, e.g. v21.03.2.
2. Check the config source (env var, conf string) actually holds the version; unset/empty values cause this error.
3. Trim whitespace only — the prefix check happens after TrimSpace, so 'v21.03.2 ' is fine but ' 21.03.2' fails (no v).
4. Verify with dgraph version which tag format your binaries use and mirror it.

Example fix

// before
FROM_VER=$(sed 's/^dgraph\///' image) # yields "21.03.0"
dgraph upgrade offline -f "$FROM_VER" -t v21.03.2
// after
FROM_VER="v$(sed 's/^dgraph\///' image)"
dgraph upgrade offline -f "$FROM_VER" -t v21.03.2

func isParsableVersion(v string) bool {
	v = strings.TrimSpace(v)
	return v != "" && strings.HasPrefix(v, "v")
}
// use: if !isParsableVersion(flagValue) { log.Fatal("version must be non-empty and start with v") }

When it happens

Trigger: Passing "" or a value like "21.03.0" (no v) to parseVersionFromString — e.g. dgraph upgrade with an empty --from/--to, or the config key holding an empty string.

Common situations: Unset environment variables interpolated into flags, YAML/config files with empty version keys, forgetting the leading v used in Dgraph release tags.

Related errors

• error: `%s` must be less than `%s`
• Key size value is too large (x > 4096)
• Key size value must be a factor of 2
• Elliptic curve value must be one of: P224, P256, P384 or P52
• error parsing flag `%s`: %w

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/eb1a312312cb7ae3. Report an issue: GitHub.