amir20/dozzle · error

error reading certificates

Error message

error reading certificates: %w

What it means

Returned by AgentTestCmd.Run when ReadCertificates fails while preparing the connectivity test client. The test command needs the same TLS certs as the agent to dial it, so cert load failure aborts the test before any network activity.

Solutions

1. Point --cert-path/--key-path at the same shared cert/key pair the agent uses.
2. Regenerate certs with `make generate` and copy both files to the testing machine.
3. Validate files: `openssl x509 -in cert.pem -noout && openssl rsa -in key.pem -check`.
4. Fix file read permissions for the current user.
5. Use a build with embedded certs instead of a bare source checkout.

Example fix

// before
./dozzle agent-test 10.0.0.5:7007  # no certs on this machine
// after
scp server:/shared/{cert.pem,key.pem} /etc/dozzle/
./dozzle agent-test --cert-path /etc/dozzle/cert.pem --key-path /etc/dozzle/key.pem 10.0.0.5:7007

[ -r "$CERT" ] && [ -r "$KEY" ] || { echo 'cert files missing/unreadable'; exit 1; }

if err := agentTestCmd.Run(args, embeddedCerts); err != nil {
  if strings.Contains(err.Error(), "error reading certificates") {
    log.Fatal().Err(err).Msg("supply the agent's shared cert/key via --cert-path/--key-path")
  }
}

When it happens

Trigger: --cert-path/--key-path point to missing, unreadable, or malformed files; key does not match the certificate; running a build without embedded certs and no files supplied.

Common situations: Testing connectivity to a remote agent from a machine without the shared certs; copied cert files got truncated in transit; wrong paths after moving the install directory.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• failed to read certificates
• failed to read certificates
• failed to parse certificate
• failed to parse certificate
• agent command is only available in server mode

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

Appendix: source

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

package cli

import (
	"context"
	"embed"
	"fmt"

	"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)