googleapis/mcp-toolbox · error

invalid Cloud SQL instance ID %q: must match %s

Error message

invalid Cloud SQL instance ID %q: must match %s

What it means

ValidateInstanceConnectionName checks the instance-ID segment of a connection name against ^[a-z][a-z0-9-]{0,97}[a-z0-9]$ (lowercase, start with a letter, end with letter/digit, up to 99 chars). Cloud SQL instance IDs follow these upstream naming rules, and this validation prevents unsafe characters from reaching generated code or DSN templates.

Source

Thrown at internal/util/cloudsqlconnect/inputvalidate.go:54

	databaseNameRe     = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_-]{0,62}$`)
)

// ValidateInstanceConnectionName splits and validates project, region, and
// instance ID per the GCP naming rules. Use this in place of plain
// ParseConnectionName when the parts will flow into generated code or shell.
func ValidateInstanceConnectionName(connName string) (project, region, instance string, err error) {
	project, region, instance, err = ParseConnectionName(connName)
	if err != nil {
		return "", "", "", err
	}
	if !projectIDRe.MatchString(project) {
		return "", "", "", fmt.Errorf("invalid project ID %q: must match %s", project, projectIDRe)
	}
	if !gcpRegionRe.MatchString(region) {
		return "", "", "", fmt.Errorf("invalid region %q: must match %s", region, gcpRegionRe)
	}
	if !cloudSQLInstanceRe.MatchString(instance) {
		return "", "", "", fmt.Errorf("invalid Cloud SQL instance ID %q: must match %s", instance, cloudSQLInstanceRe)
	}
	return project, region, instance, nil
}

// ValidateGCEResourceName checks a VM name or zone name against the standard
// GCE resource-name rule (lowercase, digits, hyphen; must start with a letter
// and not end with a hyphen, max 63 chars).
func ValidateGCEResourceName(name, kind string) error {
	if !gceResourceRe.MatchString(name) {
		return fmt.Errorf("invalid %s %q: must match %s", kind, name, gceResourceRe)
	}
	return nil
}

// ValidateDatabaseName accepts the conservative subset of database identifier
// characters that's safe in DSNs and code-snippet templates across Postgres,
// MySQL and SQL Server. It deliberately rejects quotes, semicolons, and
// whitespace even when the engine itself would accept them.

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Use the Cloud SQL instance ID from `gcloud sql instances list --format='value(name)'`
2. Convert the ID to lowercase and remove underscores/invalid characters
3. Confirm the connection name has exactly three colon-separated parts: project:region:instance

Example fix

// before
ValidateInstanceConnectionName("my-project:us-central1:My_Instance")
// after
ValidateInstanceConnectionName("my-project:us-central1:my-instance")

var cloudSQLInstanceRe = regexp.MustCompile(`^[a-z][a-z0-9-]{0,97}[a-z0-9]$`)
instance := parts[2]
if !cloudSQLInstanceRe.MatchString(instance) {
    return fmt.Errorf("instance segment %q is not a valid Cloud SQL instance ID", instance)
}

func isValidCloudSQLInstanceID(id string) bool {
    return regexp.MustCompile(`^[a-z][a-z0-9-]{0,97}[a-z0-9]$`).MatchString(id)
}

project, region, instance, err := cloudsqlconnect.ValidateInstanceConnectionName(connName)
if err != nil {
    return fmt.Errorf("connection name %q rejected: %w; instance ID must be lowercase, start with a letter", connName, err)
}

When it happens

Trigger: Passing a connection name whose final segment contains uppercase, underscores, spaces, starts with a digit or hyphen, ends with a hyphen, or is empty.

Common situations: Developer used the instance's display name or connection alias instead of the instance ID; used a Postgres database name instead of the Cloud SQL instance ID; pasted a full connection name with a trailing character.

Related errors

• invalid connection name %q: project, region, and instance mu
• invalid region %q: must match %s
• error creating instance: %w
• operation finished with error but could not marshal error ob
• operation finished with error: %s

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