{"record":{"id":"8ff69b8799e3a16f","repo":"googleapis/mcp-toolbox","slug":"multiple-vms-named-q-found-in-zones-v-please","errorCode":null,"errorMessage":"multiple VMs named %q found in zones: %v - please specify vm_zone parameter","messagePattern":"multiple VMs named %q found in zones: (.+?) - please specify vm_zone parameter","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/util/cloudsqlconnect/gce.go","lineNumber":192,"sourceCode":"\t\t\t\tfoundZones = append(foundZones, ExtractNetworkName(zone))\n\t\t\t\tif len(foundInstances) > 1 {\n\t\t\t\t\treturn stopPaging\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t})\n\tif err != nil && err != stopPaging {\n\t\treturn nil, \"\", fmt.Errorf(\"failed to search for VM: %w\", err)\n\t}\n\n\tswitch len(foundInstances) {\n\tcase 0:\n\t\treturn nil, \"\", fmt.Errorf(\"VM %q not found in project %q\", vmName, project)\n\tcase 1:\n\t\treturn foundInstances[0], foundZones[0], nil\n\tdefault:\n\t\treturn nil, \"\", fmt.Errorf(\"multiple VMs named %q found in zones: %v - please specify vm_zone parameter\", vmName, foundZones)\n\t}\n}\n\n// stringErr signals early termination from Pages without conflating with\n// real API errors. Unexported: only FindVM's Pages callback uses it.\ntype stringErr string\n\nfunc (e stringErr) Error() string { return string(e) }\n","sourceCodeStart":174,"sourceCodeEnd":201,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/util/cloudsqlconnect/gce.go#L174-L201","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run with the vm_zone parameter set to the zone containing the intended VM (e.g. us-central1-a)","List candidates with `gcloud compute instances list --filter=\"name=<vmName>\"` to see which zones hold matches, then pick the correct zone","Rename one of the duplicate VMs if zone disambiguation is undesired long-term"],"exampleFix":"// before\nFindVM(ctx, \"app-server\", \"my-project\", \"\")\n// after\nFindVM(ctx, \"app-server\", \"my-project\", \"us-central1-a\")","handlingStrategy":"validation","validationCode":"if zoneParam == \"\" {\n    return fmt.Errorf(\"vm_zone is required when VM names may be duplicated across zones\")\n}","typeGuard":"func hasZone(opts map[string]string) bool {\n    z, ok := opts[\"vm_zone\"]\n    return ok && z != \"\"\n}","tryCatchPattern":"inst, zone, err := FindVM(ctx, vmName, project, zoneParam)\nif err != nil && strings.Contains(err.Error(), \"multiple VMs named\") {\n    // recover by listing candidate zones and retrying with an explicit zone\n    return listVMZonesAndRetry(ctx, vmName, project)\n}","preventionTips":["Always supply vm_zone when VM names are templated across zones","Keep VM names unique per project, not per zone","Cache project-wide instance inventories so duplicates are detected before calls"],"tags":["gcp","compute-engine","ambiguous-parameter"],"backgroundTag":"ambiguous-resource-name","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}