vitessio/vitess · error

unable to construct a LocalController instance because param

Error message

unable to construct a LocalController instance because param: %s is missing in params: %v

What it means

The 'local' schema manager controller factory requires the schema change directory parameter (SchemaChangeDirName, e.g. 'schema-change-dir') in the params map. When that key is missing, NewLocalController cannot be built and this error is returned at registration/lookup time. It names both the missing key and the full params map for diagnosis.

Source

Thrown at go/vt/schemamanager/local_controller.go:231

		}
	}
	fmt.Fprintf(logFile, "-- Rows returned: %d\n", rowsReturned)
	fmt.Fprintf(logFile, "-- Rows affected: %d\n", rowsAffected)
	logFile.WriteString("-- \n")
	fmt.Fprintf(logFile, "-- ran in %fs\n", result.TotalTimeSpent.Seconds())
	logFile.WriteString("-- Execution succeeded\n")
	return nil
}

var _ Controller = (*LocalController)(nil)

func init() {
	RegisterControllerFactory(
		"local",
		func(params map[string]string) (Controller, error) {
			schemaChangeDir, ok := params[SchemaChangeDirName]
			if !ok {
				return nil, fmt.Errorf("unable to construct a LocalController instance because param: %s is missing in params: %v", SchemaChangeDirName, params)
			}
			return NewLocalController(schemaChangeDir), nil
		},
	)
}

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Add the schema change directory to params under the SchemaChangeDirName key (flag: --schema-change-dir)
2. Verify the controller name/type actually matches your setup ('local' vs other registered controllers)
3. Check the error's params dump to confirm which keys were actually passed

Example fix

// before
params := map[string]string{"controller": "local"}
// after
params := map[string]string{"controller": "local", "schema-change-dir": "/vt/schema-change-dir"}

if _, ok := params["schema-change-dir"]; !ok {
  return fmt.Errorf("--schema-change-dir is required for the local controller")
}

When it happens

Trigger: Calling schemamanager.NewSchemaManager (or initSchema) with controller type 'local' but the params map lacking the schema-change-dir key.

Common situations: Misconfigured vtctl/vtctld schema change invocation where the local directory flag was omitted; programmatically building params and forgetting the constant key; copy-pasting config from a non-local controller type.

Related errors

• --batch-size requires 'direct' ddl_strategy
• --batch-size conflicts with --uuid-list. Batching does not s
• --batch-size only allowed when all queries are CREATE TABLE|
• there is no data sourcer factory with name: %s
• --s3-backup-storage-bucket required

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