googleapis/mcp-toolbox · error

multiple VMs named %q found in zones: %v - please specify vm

Error message

multiple VMs named %q found in zones: %v - please specify vm_zone parameter

What it means

GCE allows instances with the same name in different zones. When FindVM's AggregatedList paging finds more than one instance matching vmName in the project, the result is ambiguous, so it refuses to guess and returns this error telling the caller to disambiguate with the vm_zone parameter.

Source

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

				foundZones = append(foundZones, ExtractNetworkName(zone))
				if len(foundInstances) > 1 {
					return stopPaging
				}
			}
		}
		return nil
	})
	if err != nil && err != stopPaging {
		return nil, "", fmt.Errorf("failed to search for VM: %w", err)
	}

	switch len(foundInstances) {
	case 0:
		return nil, "", fmt.Errorf("VM %q not found in project %q", vmName, project)
	case 1:
		return foundInstances[0], foundZones[0], nil
	default:
		return nil, "", fmt.Errorf("multiple VMs named %q found in zones: %v - please specify vm_zone parameter", vmName, foundZones)
	}
}

// stringErr signals early termination from Pages without conflating with
// real API errors. Unexported: only FindVM's Pages callback uses it.
type stringErr string

func (e stringErr) Error() string { return string(e) }

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Re-run with the vm_zone parameter set to the zone containing the intended VM (e.g. us-central1-a)
2. List candidates with `gcloud compute instances list --filter="name=<vmName>"` to see which zones hold matches, then pick the correct zone
3. Rename one of the duplicate VMs if zone disambiguation is undesired long-term

Example fix

// before
FindVM(ctx, "app-server", "my-project", "")
// after
FindVM(ctx, "app-server", "my-project", "us-central1-a")

if zoneParam == "" {
    return fmt.Errorf("vm_zone is required when VM names may be duplicated across zones")
}

func hasZone(opts map[string]string) bool {
    z, ok := opts["vm_zone"]
    return ok && z != ""
}

inst, zone, err := FindVM(ctx, vmName, project, zoneParam)
if err != nil && strings.Contains(err.Error(), "multiple VMs named") {
    // recover by listing candidate zones and retrying with an explicit zone
    return listVMZonesAndRetry(ctx, vmName, project)
}

When it happens

Trigger: Calling FindVM (via Invoke) with a vm_name that exists in two or more zones of the project and omitting (or leaving empty) the vm_zone parameter.

Common situations: Teams replicate identically-named VMs across zones (e.g. us-central1-a and us-central1-b) for availability; a developer assumes the name is unique project-wide and doesn't pass vm_zone.

Related errors

• failed to build token-scoped Compute Engine client: %w
• failed to search for VM: %w
• VM %q not found in project %q
• invalid %s %q: must match %s
• ErrReadSizeLimitExceeded

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