googleapis/mcp-toolbox · error

invalid Cloud SQL instance ID

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.

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
• invalid region : must match
• could not marshal operation
• could not unmarshal operation
• error creating backup

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

Appendix: 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)