no host matching found; call list_hosts to see available…

Error message

no host matching %q found; call list_hosts to see available hosts

What it means

resolveHostRef matches the hostRef string against host names (case-insensitive). Zero matches yields this error directing the caller to list_hosts. Multiple matches produce a different error listing the candidates.

Solutions

Run list_hosts to see connected host names and ids
Use the exact host id instead of the name to avoid ambiguity
Reconnect the remote agent/fix connectivity if the expected host is missing

Example fix

// before
fetchLogs({container_id: "abc", host: "node-1.prod"})
// after
const hosts = await listHosts({})
const h = hosts.find(x => x.name === "node-1")  // exact listed name
fetchLogs({container_id: "abc", host: h.id})

Defensive patterns

Strategy: validation

Validate before calling

const hosts = await listHosts({}); if (hostRef && !hosts.some(h => h.id === hostRef || h.name.toLowerCase() === hostRef.toLowerCase())) throw new Error('host ' + hostRef + ' not connected');

Type guard

null

Try / catch

try { await fetchLogs({container_id: id, host: ref}) } catch (e) { if (/no host matching/.test(e.message)) { const hosts = await listHosts({}); console.warn('available hosts:', hosts.map(h => h.name)); } }

Prevention

Cache host ids from list_hosts instead of names
Re-list hosts after agent reconnects; names can disappear when hosts go offline
Prefer the host id form to sidestep name ambiguity

When it happens

Trigger: Calling a container tool with a host argument that matches no connected host name: typo, hostname that changed, or agent host currently disconnected so it is absent from the host list.

Common situations: Referring to hosts by DNS name when dozzle uses a different display name; Swarm node renamed; remote agent down so the host disappeared from HostService.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of amir20/dozzle@d9463cbe21 (2026-09-07). Data as JSON: /api/errors/3a7fe32ae1f7d946. Report an issue: GitHub.

Appendix: source

Thrown at internal/cloud/tools_resolve.go:223

	}
	return false
}

// resolveHostRef resolves a host reference (id or name) to its host id.
func resolveHostRef(hostRef string, deps ToolDeps) (string, error) {
	hosts := deps.HostService.Hosts()
	var byName []container.Host
	for _, h := range hosts {
		if h.ID == hostRef {
			return h.ID, nil
		}
		if strings.EqualFold(h.Name, hostRef) {
			byName = append(byName, h)
		}
	}
	switch len(byName) {
	case 0:
		return "", fmt.Errorf("no host matching %q found; call list_hosts to see available hosts", hostRef)
	case 1:
		return byName[0].ID, nil
	default:
		names := make([]string, len(byName))
		for i, h := range byName {
			names[i] = fmt.Sprintf("%s (id %s)", h.Name, h.ID)
		}
		return "", fmt.Errorf("host name %q is ambiguous; matches: %s. Pass the host id instead", hostRef, strings.Join(names, "; "))
	}
}

// ambiguousError builds an actionable error listing every candidate so the
// caller can re-issue the call unambiguously. The hint is tailored to the
// candidate set because the LLM reads it to choose its next action: when the
// candidates span multiple hosts, host_id disambiguates; when they all sit on
// one host, host_id is useless and only the exact id or full name will do.
func ambiguousError(containerRef, hostRef string, candidates []container.Container, hostNames map[string]string) error {
	parts := make([]string, len(candidates))

View on GitHub (pinned to d9463cbe21)