vitessio/vitess · critical

error creating vtctldclient: %w

Error message

error creating vtctldclient: %w

What it means

cluster.New fails when vtctldclient.New cannot create the vtctld client proxy for the cluster, after the vtsql proxy was created successfully. The wrapped error is the underlying client construction failure, typically connection setup to the vtctld server.

Source

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

	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)
	if err != nil {
		return nil, fmt.Errorf("error creating vtsql proxy: %w", err)
	}

	cluster.Vtctld, err = vtctldclient.New(ctx, vtctldCfg)
	if err != nil {
		return nil, fmt.Errorf("error creating vtctldclient: %w", err)
	}

	if cfg.TabletFQDNTmplStr != "" {
		cluster.TabletFQDNTmpl, err = template.New(cluster.ID + "-tablet-fqdn").Parse(cfg.TabletFQDNTmplStr)
		if err != nil {
			return nil, fmt.Errorf("failed to parse tablet fqdn template %s: %w", cfg.TabletFQDNTmplStr, err)
		}
	}

	cluster.backupReadPool = cfg.BackupReadPoolConfig.NewReadPool()
	cluster.schemaReadPool = cfg.SchemaReadPoolConfig.NewReadPool()
	cluster.topoRWPool = cfg.TopoRWPoolConfig.NewRWPool()
	cluster.topoReadPool = cfg.TopoReadPoolConfig.NewReadPool()
	cluster.workflowReadPool = cfg.WorkflowReadPoolConfig.NewReadPool()

	cluster.emergencyFailoverPool = cfg.EmergencyFailoverPoolConfig.NewRWPool()
	cluster.failoverPool = cfg.FailoverPoolConfig.NewRWPool()

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the vtctld server is running and reachable at the configured address
2. Check TLS configuration (certs, CA) for the vtctldclient
3. Correct the vtctld flags and restart vtadmin

// before starting vtadmin, verify vtctld reachability
host, port := vtctldAddrFromFlags(cfg.VtctldFlags)
conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, port), 3*time.Second)
if err != nil {
    return fmt.Errorf("vtctld %s:%s unreachable: %w", host, port, err)
}
conn.Close()

c, err := cluster.BuildCluster(ctx, cfg)
if err != nil {
    if strings.Contains(err.Error(), "error creating vtctldclient") {
        return fmt.Errorf("cannot reach vtctld for cluster %q: %w", cfg.ID, err)
    }
    return err
}

When it happens

Trigger: vtctldclient.New(ctx, vtctldCfg) errors during cluster.BuildCluster — vtctld unreachable, TLS/cert problems, or invalid resolved connection config.

Common situations: vtctld down or wrong host/port in flags; mTLS cert/key mismatch; network policy blocking vtadmin->vtctld.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• error creating vtsql proxy: %w
• failed to transition from state %s
• invalid key:value pair
• parse error
• no port variable in mysql

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