vitessio/vitess · error

%s

Error message

%s

What it means

NewVReplicationConfig validates user-supplied vreplication config flags. Unknown flag keys are accumulated into a joined error message ('unknown vreplication config flag: <k>', comma-separated for multiple), and the function returns the (partial) config together with this error so misconfiguration is surfaced at startup.

Source

Thrown at go/vt/vttablet/common/config.go:259

			if err != nil {
				errors = append(errors, getError(k, v))
			} else {
				c.VStreamBinlogRotationThresholdOverride = true
				c.VStreamBinlogRotationThreshold = value
			}
		case "max-row-json-bytes":
			value, err := strconv.ParseInt(v, 10, 64)
			if err != nil || value < 0 {
				errors = append(errors, getError(k, v))
			} else {
				c.MaxRowJSONBytes = value
			}
		default:
			errors = append(errors, "unknown vreplication config flag: "+k)
		}
	}
	if len(errors) > 0 {
		return c, fmt.Errorf("%s", strings.Join(errors, ", "))
	}
	return c, nil
}

// Map returns a map of the VReplicationConfig: the keys are the flag names and the values are string representations.
// Used in tests to compare the expected and actual configuration values and in validations to check if the user-provided
// keys are one of those that are supported.
func (c VReplicationConfig) Map() map[string]string {
	return map[string]string{
		"vreplication-experimental-flags":         strconv.FormatInt(c.ExperimentalFlags, 10),
		"vreplication-net-read-timeout":           strconv.Itoa(c.NetReadTimeout),
		"vreplication-net-write-timeout":          strconv.Itoa(c.NetWriteTimeout),
		"vreplication-copy-phase-duration":        c.CopyPhaseDuration.String(),
		"vreplication-retry-delay":                c.RetryDelay.String(),
		"vreplication-max-time-to-retry-on-error": c.MaxTimeToRetryError.String(),
		"relay-log-max-size":                      strconv.Itoa(c.RelayLogMaxSize),
		"relay_log_max_size":                      strconv.Itoa(c.RelayLogMaxSize),
		"relay-log-max-items":                     strconv.Itoa(c.RelayLogMaxItems),

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix or remove the unknown key from the vreplication flags on the vttablet command line/config
2. List valid flags (`vttablet --help | grep vreplication` or common/config.go NewVReplicationConfig) and use an exact match
3. After a Vitess upgrade, diff your flags against the new version's accepted keys — renamed flags cause this at boot
4. If a flag was deprecated, migrate to its replacement rather than passing it through

Example fix

// before
--vreplication_track_er_heartbeat=true
// after
--vreplication_track_heartbeat=true

flags := map[string]bool{"vreplication_track_heartbeat": true, /* ...known keys */}
for k := range userFlags {
    if !flags[k] { return fmt.Errorf("unknown flag %s", k) }
}

c, err := common.NewVReplicationConfig(m)
if err != nil {
    for _, e := range strings.Split(err.Error(), ", ") { log.Warn(e) }
}

When it happens

Trigger: Constructing/refreshing the VReplicationConfig (config refresh loop or TestMaxRowJSONBytesOverride-style overrides) with a key that is not a known vreplication config flag — typically from a bad command-line flag or wrong key in the config source.

Common situations: Typo like 'vreplication_track_er_heartbeat' misspelled; flag renamed/removed in a newer Vitess version; leftover flags in an old config file after upgrade.

Related errors

• failed to process config options: %v
• only count(*) is supported: %v
• unsupported multiple columns in sum clause: %v
• unsupported non-column name in sum clause: %v
• unsupported subquery: %v

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