amir20/dozzle · error

invalid agent endpoint

Error message

invalid agent endpoint: %s

What it means

ParseEndpoint returns "invalid agent endpoint: %s" when an endpoint string of the form "address|name|group" has more than 3 pipe-separated parts or an empty address. The address is mandatory; name and group are optional extras.

Solutions

1. Correct the endpoint to "address", "address|name", or "address|name|group" with exactly one non-empty address
2. Remove any '|' characters from agent display names or groups, or escape/rename them
3. Check the DOZZLE_REMOTE_AGENT env/label value for stray separators, whitespace, or empty entries before passing them to NewClient
4. Validate each endpoint with agent.ParseEndpoint at config load time and fail fast with a clear message

Example fix

// before
endpoint := "agent:7007||Team|Prod" // 4 parts
client, err := agent.NewClient(endpoint, certs)
// after
endpoint := "agent:7007|Team|Prod"
client, err := agent.NewClient(endpoint, certs)

parts := strings.Split(endpoint, "|")
if len(parts) > 3 || parts[0] == "" {
    return fmt.Errorf("endpoint must be address[|name[|group]], got %q", endpoint)
}

func validAgentEndpoint(e string) bool { _, _, _, err := agent.ParseEndpoint(e); return err == nil }

addr, name, group, err := agent.ParseEndpoint(cfg.AgentEndpoint)
if err != nil { log.Fatal().Err(err).Msg("fix DOZZLE_REMOTE_AGENT format: address|name|group") }

When it happens

Trigger: agent.NewClient or agent.Hosts receives an endpoint string where strings.Split(e, "|") yields >3 parts, or the first part (address) is empty, e.g. "|Agent", "a|b|c|d", or "".

Common situations: Multi-host config env var (DOZZLE_REMOTE_AGENT / agent hosts list) with a trailing or doubled pipe like "host:7007|Agent|" is fine but "host:7007|||x" is not; leading pipe after an empty host; copy-paste adding a name containing a '|' character.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• failed to connect to
• invalid format: key is empty
• failed to parse certificate
• EOF error while converting gRPC to error
• unknown error: with

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

Appendix: source

Thrown at internal/agent/client.go:91

	}

	client := pb.NewAgentServiceClient(conn)

	return &Client{
		client:       client,
		conn:         conn,
		endpoint:     endpoint,
		nameOverride: nameOverride,
		group:        group,
	}, nil
}

// ParseEndpoint splits an agent endpoint of the form "address|name|group" into
// its parts. Name and group are optional; address is required.
func ParseEndpoint(endpoint string) (string, string, string, error) {
	parts := strings.Split(endpoint, "|")
	if len(parts) > 3 || parts[0] == "" {
		return "", "", "", fmt.Errorf("invalid agent endpoint: %s", endpoint)
	}

	name := ""
	if len(parts) >= 2 {
		name = parts[1]
	}

	group := ""
	if len(parts) == 3 {
		group = parts[2]
	}

	return parts[0], name, group, nil
}

func rpcErrToErr(err error) error {
	if err == nil {
		return nil

View on GitHub (pinned to d9463cbe21)