vitessio/vitess · error

failed to process config options: %v

Error message

failed to process config options: %v

What it means

After parsing the workflow options JSON, processWorkflowOptions passes options.Config to vttablet.NewVReplicationConfig. If the config blob is invalid (bad format, unknown fields, validation failure), the controller cannot be created and returns `failed to process config options: <err>`.

Source

Thrown at go/vt/vttablet/tabletmanager/vreplication/controller.go:111

// workflowTypeName returns the human-readable name for the workflow type
// (e.g. "OnlineDDL", "Reshard", "MoveTables").
func (ct *controller) workflowTypeName() string {
	return binlogdatapb.VReplicationWorkflowType(ct.workflowType).String()
}

func processWorkflowOptions(params map[string]string) (*vttablet.VReplicationConfig, error) {
	options, ok := params["options"]
	if !ok {
		options = "{}"
	}
	var workflowOptions vtctldata.WorkflowOptions
	if err := json.Unmarshal([]byte(options), &workflowOptions); err != nil {
		return nil, fmt.Errorf("failed to parse options column: %v", err)
	}
	workflowConfig, err := vttablet.NewVReplicationConfig(workflowOptions.Config)
	if err != nil {
		return nil, fmt.Errorf("failed to process config options: %v", err)
	}
	return workflowConfig, nil
}

// newController creates a new controller. Unless a stream is explicitly 'Stopped',
// this function launches a goroutine to perform continuous vreplication.
func newController(ctx context.Context, params map[string]string, dbClientFactory func() binlogplayer.DBClient, mysqld mysqlctl.MysqlDaemon, ts *topo.Server, cell string, blpStats *binlogplayer.Stats, vre *Engine, tpo discovery.TabletPickerOptions) (*controller, error) {
	if blpStats == nil {
		blpStats = binlogplayer.NewStats()
	}
	workflowConfig, err := processWorkflowOptions(params)
	if err != nil {
		return nil, err
	}
	tabletTypesStr := workflowConfig.TabletTypesStr
	ct := &controller{
		vre:             vre,
		dbClientFactory: dbClientFactory,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the `config` value in the workflow's options column and correct it against the VReplicationConfig schema for your Vitess version
2. Remove the `config` key (use `{}` or options without config) to fall back to defaults if custom config isn't required
3. Recreate the workflow with a valid config rather than editing stored state, if the config cannot be repaired in place
4. Check release notes for VReplicationConfig format changes if the workflow was created on an older Vitess

Example fix

// before
options = '{"config":"enable_throttler: maybe"}' // invalid config value
// after
options = '{"config":"enable_throttler: true"}' // valid, or simply '{}':

// validate options.Config parses before storing the workflow
var wfOpts vtctldata.WorkflowOptions
if err := json.Unmarshal([]byte(optionsCol), &wfOpts); err != nil { return err }
if _, err := vttablet.NewVReplicationConfig(wfOpts.Config); err != nil {
  return fmt.Errorf("workflow config invalid: %w", err)
}

func hasValidConfig(optionsJSON string) bool {
  var o vtctldata.WorkflowOptions
  if json.Unmarshal([]byte(optionsJSON), &o) != nil { return false }
  if o.Config == "" { return true }
  _, err := vttablet.NewVReplicationConfig(o.Config)
  return err == nil
}

ct, err := newController(ctx, env, ...)
if err != nil {
  if strings.Contains(err.Error(), "failed to process config options") {
    // fix or remove the `config` key in the workflow options, then retry
  }
  return err
}

When it happens

Trigger: The workflow's options JSON contains a `config` key whose value fails NewVReplicationConfig validation — e.g. invalid YAML/JSON config content, unsupported settings, or config referencing unknown parameters.

Common situations: Users enabling vreplication workflow configuration (e.g. throttler/copy-phase settings via WorkflowOptions.Config) with typos or unsupported fields; config format changed between Vitess versions so an old stored config no longer validates; partial config written by tooling.

Related errors

• stream needs a position or a table to copy
• partial row image encountered: ensure binlog_row_image is se
• failed to instantiate throttler: %v
• no binlog player client factory named %v
• tablet %s has a replication lag of %d seconds which is beyon

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