invalid connection name format %q: expected project:region:i

Error message

invalid connection name format %q: expected project:region:instance

What it means

ParseConnectionName splits a Cloud SQL instance connection name of the form project:region:instance. The string must contain exactly three colon-separated non-empty parts; anything else (wrong number of colons) yields this error.

Source

Thrown at internal/util/cloudsqlconnect/gce.go:35

import (
	"context"
	"fmt"
	"strings"
	"sync"

	"golang.org/x/oauth2"
	"google.golang.org/api/compute/v1"
	"google.golang.org/api/option"
	sqladmin "google.golang.org/api/sqladmin/v1"
)

// ParseConnectionName splits a Cloud SQL instance connection name
// ("project:region:instance") into its three components, rejecting any input
// that doesn't have exactly three non-empty parts.
func ParseConnectionName(connName string) (project, region, instance string, err error) {
	parts := strings.Split(connName, ":")
	if len(parts) != 3 {
		return "", "", "", fmt.Errorf("invalid connection name format %q: expected project:region:instance", connName)
	}
	if parts[0] == "" || parts[1] == "" || parts[2] == "" {
		return "", "", "", fmt.Errorf("invalid connection name %q: project, region, and instance must all be non-empty", connName)
	}
	return parts[0], parts[1], parts[2], nil
}

// ExtractNetworkName pulls the trailing element off a fully-qualified network
// or subnetwork resource path. Idempotent for inputs that are already a name.
func ExtractNetworkName(path string) string {
	idx := strings.LastIndex(path, "/")
	if idx == -1 {
		return path
	}
	return path[idx+1:]
}

// IsSameVPC reports whether the Cloud SQL VPC and the GCE VM VPC resolve to

View on GitHub (pinned to 8cc6e09de2)

Solutions

Provide the full connection name as project:region:instance, e.g. my-project:us-central1:my-instance
Copy the connection name verbatim from the Cloud SQL console / 'gcloud sql instances describe'
If the project is domain-scoped, use the short project ID or adjust parsing since colons in the project change segment count

Example fix

// before
conn := "my-project~us-central1~my-instance"
p, r, i, err := cloudsqlconnect.ParseConnectionName(conn)
// after
conn := "my-project:us-central1:my-instance"
p, r, i, err := cloudsqlconnect.ParseConnectionName(conn)

Defensive patterns

Strategy: validation

Validate before calling

func validConnName(conn string) bool {
    parts := strings.Split(conn, ":")
    return len(parts) == 3 && parts[0] != "" && parts[1] != "" && parts[2] != ""
}
if !validConnName(connName) {
    return fmt.Errorf("bad Cloud SQL connection name: %q", connName)
}

Try / catch

p, r, inst, err := cloudsqlconnect.ParseConnectionName(connName)
if err != nil {
    return fmt.Errorf("check connection name %q: must be project:region:instance: %w", connName, err)
}

Prevention

Copy connection names verbatim from Cloud SQL console or gcloud output
Never hand-build connection names with '~' separators
Assert config values with a format check before use

When it happens

Trigger: Passing a connection name with fewer or more than three colon-separated segments, e.g. 'my-project~my-region~my-instance' (domain-scoped projects use ~), 'project:instance', or an empty string, to ParseConnectionName or ValidateInstanceConnectionName.

Common situations: Using the MySQL-style '~' separator instead of ':'; omitting the region; passing a database name or host instead of the connection name; domain-scoped project IDs ('example.com:my-project') shifting the segment count.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/2e3bb4f26a1c0542. Report an issue: GitHub.