{"record":{"id":"e40ba472cc367121","repo":"amir20/dozzle","slug":"host-name-q-is-ambiguous-matches-s-pass-the-h","errorCode":null,"errorMessage":"host name %q is ambiguous; matches: %s. Pass the host id instead","messagePattern":"host name %q is ambiguous; matches: (.+?)\\. Pass the host id instead","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cloud/tools_resolve.go","lineNumber":231,"sourceCode":"\tfor _, h := range hosts {\n\t\tif h.ID == hostRef {\n\t\t\treturn h.ID, nil\n\t\t}\n\t\tif strings.EqualFold(h.Name, hostRef) {\n\t\t\tbyName = append(byName, h)\n\t\t}\n\t}\n\tswitch len(byName) {\n\tcase 0:\n\t\treturn \"\", fmt.Errorf(\"no host matching %q found; call list_hosts to see available hosts\", hostRef)\n\tcase 1:\n\t\treturn byName[0].ID, nil\n\tdefault:\n\t\tnames := make([]string, len(byName))\n\t\tfor i, h := range byName {\n\t\t\tnames[i] = fmt.Sprintf(\"%s (id %s)\", h.Name, h.ID)\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"host name %q is ambiguous; matches: %s. Pass the host id instead\", hostRef, strings.Join(names, \"; \"))\n\t}\n}\n\n// ambiguousError builds an actionable error listing every candidate so the\n// caller can re-issue the call unambiguously. The hint is tailored to the\n// candidate set because the LLM reads it to choose its next action: when the\n// candidates span multiple hosts, host_id disambiguates; when they all sit on\n// one host, host_id is useless and only the exact id or full name will do.\nfunc ambiguousError(containerRef, hostRef string, candidates []container.Container, hostNames map[string]string) error {\n\tparts := make([]string, len(candidates))\n\tsameHost := true\n\tfor i, c := range candidates {\n\t\tparts[i] = fmt.Sprintf(\"%s (id %s, %s, on host %s)\", c.Name, shortID(c.ID), describeState(c), resolveHostName(c.Host, hostNames))\n\t\tif c.Host != candidates[0].Host {\n\t\t\tsameHost = false\n\t\t}\n\t}\n","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/amir20/dozzle/blob/d9463cbe21874e44ab79db6fa63e746ca7d22928/internal/cloud/tools_resolve.go#L213-L249","documentation":"resolveHostRef accepts a host id or name; when a name matches more than one host it refuses to guess and lists every match as 'Name (id X)'. This is a cloud-tool resolution error meant for an LLM caller, so the message is intentionally actionable and tells it to re-issue with the host id.","triggerScenarios":"resolveHostRef is given a hostRef that is not a known id but matches >1 host by name; raised in the default branch after byName lookup returns multiple entries (len(byName) > 1). Called from matchContainerTier in the cloud tools pipeline.","commonSituations":"Two hosts registered with the same name (e.g. duplicate agent enrollment, Swarm nodes sharing a display name, a host re-added under an existing name). An LLM tool call passing 'server' or 'remote' where multiple hosts share that label.","solutions":["Call resolveHostRef again passing the host id (the second field shown in the message) instead of the name","List available hosts and rename one via its config so names are unique","If the tool schema accepts host_id, supply host_id explicitly in the tool call arguments"],"exampleFix":"// before\nresolveHostRef(ctx, deps, \"server\")\n// after\nresolveHostRef(ctx, deps, \"abc123\") // id shown in the ambiguity message","handlingStrategy":"validation","validationCode":"ids, names := listHosts(ctx, deps)\nnameCounts := map[string]int{}\nfor _, h := range hosts { nameCounts[h.Name]++ }\nfunc isUnambiguousHost(ref string, hosts []Host) bool {\n  for _, h := range hosts { if h.ID == ref { return true } }\n  n := 0\n  for _, h := range hosts { if h.Name == ref { n++ } }\n  return n == 1\n}","typeGuard":"func hostRefIsID(ref string, hosts []Host) bool {\n  for _, h := range hosts { if h.ID == ref { return true } }\n  return false\n}","tryCatchPattern":null,"preventionTips":["Always pass host ids, not names, in cloud tool calls","Keep host names unique across the deployment","When an ambiguity message appears, reuse the (id X) value it prints"],"tags":["cloud-tools","host-resolution","ambiguity"],"backgroundTag":"invalid-identifier","analyzedSha":"d9463cbe21874e44ab79db6fa63e746ca7d22928","analyzedAt":"2026-09-07T10:08:55.855Z","contentChangedAt":"2026-09-07T10:08:55.855Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}