vitessio/vitess · error

cannot parse VTPORTSTART: %v

Error message

cannot parse VTPORTSTART: %v

What it means

getPortStart in go/testfiles/ports.go reads the VTPORTSTART environment variable and panics if it is not an integer. This is test-infrastructure code: it fails fast at test setup when the port-range override is malformed, since test ports cannot be allocated reliably without it.

Source

Thrown at go/testfiles/ports.go:83

	GoVtVtctlWorkflowPort     = vtPortStart + 15 // etcd client URL
	GoVtVtctlWorkflowPeerPort = vtPortStart + 16 // etcd peer URL
)

// Zookeeper server ID definitions. Unit tests may run at the
// same time, so they can't use the same Zookeeper server IDs.
var (
	// GoVtTopoZk2topoZkID is used by the go/vt/topo/zk2topo package.
	GoVtTopoZk2topoZkID = 1
)

func getPortStart() int {
	env := os.Getenv("VTPORTSTART")
	if env == "" {
		env = "6700"
	}
	portStart, err := strconv.Atoi(env)
	if err != nil {
		panic(fmt.Errorf("cannot parse VTPORTSTART: %v", err))
	}
	return portStart
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Unset VTPORTSTART to use the default 6700, or set it to a plain integer (e.g. export VTPORTSTART=6700)
2. Strip whitespace/quotes/units from the variable in your test wrapper script
3. Check CI config files for the variable definition and correct the value

Example fix

// before
export VTPORTSTART="6700/tcp"
// after
export VTPORTSTART=6700

if v := os.Getenv("VTPORTSTART"); v != "" {
	if _, err := strconv.Atoi(v); err != nil {
		return fmt.Errorf("VTPORTSTART must be an integer, got %q", v)
	}
}

func mustPortStart() int {
	defer func() {
		if r := recover(); r != nil {
			log.Error("bad VTPORTSTART; defaulting", slog.Any("panic", r))
		}
	}()
	return vtPortStart()
}

When it happens

Trigger: Setting VTPORTSTART to a non-numeric value (e.g. "67a0", "" handled by default, but "6700 " with whitespace or "67,00" fails) before running Vitess tests.

Common situations: CI environment variable set with stray characters or quotes; local wrapper scripts exporting VTPORTSTART with a suffix; copy-paste including units like "6700/tcp".

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• err
• ReadFile cannot be called on read-write backup
• AddFile cannot be called on read-only backup
• EndBackup cannot be called on read-only backup
• AbortBackup cannot be called on read-only backup

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/42caec66231f0f8b. Report an issue: GitHub.