vitessio/vitess · critical

error creating vtsql connection config: %w

Error message

error creating vtsql connection config: %w

What it means

cluster.New fails when vtsql.Parse cannot build the vtgate SQL connection config from the cluster's proto representation and the provided vtsql flags. The wrap keeps the parse error (unknown flag, bad value) as the cause. It occurs at vtadmin startup, before any connection is actually made.

Source

Thrown at go/vt/vtadmin/cluster/cluster.go:122

		cfg:  cfg,
	}

	discoargs := buildPFlagSlice(cfg.DiscoveryFlagsByImpl[cfg.DiscoveryImpl])

	disco, err := discovery.New(cfg.DiscoveryImpl, cluster.ToProto(), discoargs)
	if err != nil {
		return nil, fmt.Errorf("error creating discovery impl (%s): %w", cfg.DiscoveryImpl, err)
	}

	cluster.Discovery = disco

	protocluster := cluster.ToProto()

	vtsqlargs := buildPFlagSlice(cfg.VtSQLFlags)

	vtsqlCfg, err := vtsql.Parse(protocluster, disco, vtsqlargs)
	if err != nil {
		return nil, fmt.Errorf("error creating vtsql connection config: %w", err)
	}

	for _, opt := range cfg.vtsqlConfigOpts {
		vtsqlCfg = opt(vtsqlCfg)
	}

	vtctldargs := buildPFlagSlice(cfg.VtctldFlags)

	vtctldCfg, err := vtctldclient.Parse(protocluster, disco, vtctldargs)
	if err != nil {
		return nil, fmt.Errorf("error creating vtctldclient proxy config: %w", err)
	}

	for _, opt := range cfg.vtctldConfigOpts {
		vtctldCfg = opt(vtctldCfg)
	}

	cluster.DB, err = vtsql.New(ctx, vtsqlCfg)

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Fix the vtsql flags in the vtadmin cluster config (vtgate addresses, target, credentials)
2. Run vtadmin with only the documented vtsql flags and add back one at a time
3. Verify flag names against the vtsql package for your vitess version

Example fix

// before
vt: "-vtgate-host badhost -vtgate-port notaport"
// after
vt: "-vtgate-host vtgate.example.com -vtgate-port 15999"

// pre-validate vtsql flags before BuildCluster
if err := validateFlagNames("vtsql", cfg.VtSQLFlags); err != nil {
    return fmt.Errorf("bad vtsql flags: %w", err)
}

c, err := cluster.BuildCluster(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "vtsql connection config") {
        return fmt.Errorf("check --vt flags for cluster %q: %w", cfg.ID, err)
    }
    return err
}

When it happens

Trigger: cfg.VtSQLFlags contains an unknown/invalid flag (e.g. wrong vtgate target or credentials flag) that vtsql.Parse rejects.

Common situations: Misconfigured vtgate host/port or keyspaces/shards target string; flag name that does not exist on this vitess version; passing pflags with malformed values.

Related errors

• error creating vtctldclient proxy config: %w
• error creating discovery impl (%s): %w
• error creating vtsql proxy: %w
• failed to parse tablet fqdn template %s: %w
• cannot load credentials from path template %s: %w

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