amir20/dozzle · error

error connecting to agent

Error message

error connecting to agent: %w

What it means

Returned by AgentTestCmd.Run when agent.NewClient fails to build or dial the gRPC connection to the agent endpoint. This wraps dial-time errors: bad address syntax, DNS failure, or TLS handshake rejection (cert mismatch between tester and agent).

Solutions

1. Confirm the agent is listening: `nc -zv <host> 7007` from the test machine.
2. Use the exact shared cert pair: --cert-path/--key-path matching the agent's certs.
3. Check the address format is host:port, e.g. 10.0.0.5:7007.
4. Open the firewall for the agent port on the target host.
5. Regenerate one shared cert pair and deploy it to both sides.

Example fix

// before
./dozzle agent-test 10.0.0.5  # missing port, wrong certs
// after
./dozzle agent-test --cert-path shared-cert.pem --key-path shared-key.pem 10.0.0.5:7007

nc -zv "${ADDR%%:*}" "${ADDR##*:}" || { echo "agent unreachable at $ADDR"; exit 1; }

if err := agentTestCmd.Run(args, embeddedCerts); err != nil {
  if strings.Contains(err.Error(), "error connecting to agent") {
    log.Fatal().Err(err).Msg("verify host:port, agent running, and matching TLS certs")
  }
}

When it happens

Trigger: Wrong/typo'd positional address (host:port); agent not running on the target port; TLS certs on the test machine differ from the agent's shared certs, causing handshake failure.

Common situations: Testing against an agent whose certs were regenerated separately; firewall dropping the port; address given without port so gRPC dial fails; hostname unresolvable from the test machine.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• failed to parse certificate
• failed to parse certificate
• failed to create agent server
• failed to connect to
• EOF error while converting gRPC to error

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

Appendix: source

Thrown at internal/support/cli/agent_test_command.go:26

	"github.com/amir20/dozzle/internal/agent"
	"github.com/rs/zerolog/log"
)

type AgentTestCmd struct {
	Address string `arg:"positional"`
}

func (at *AgentTestCmd) Run(args Args, embeddedCerts embed.FS) error {
	certs, err := ReadCertificates(embeddedCerts, args.CertPath, args.KeyPath)
	if err != nil {
		return fmt.Errorf("error reading certificates: %w", err)
	}

	log.Info().Str("endpoint", args.AgentTest.Address).Msg("Connecting to agent")

	agent, err := agent.NewClient(args.AgentTest.Address, certs)
	if err != nil {
		return fmt.Errorf("error connecting to agent: %w", err)
	}
	ctx, cancel := context.WithTimeout(context.Background(), args.Timeout)
	defer cancel()
	host, err := agent.Host(ctx)
	if err != nil {
		return fmt.Errorf("error fetching host info for agent: %w", err)
	}

	log.Info().Str("endpoint", args.AgentTest.Address).Str("version", host.AgentVersion).Str("name", host.Name).Str("id", host.ID).Msg("Successfully connected to agent")

	return nil
}

View on GitHub (pinned to d9463cbe21)