amir20/dozzle · error

agent command is only available in server mode

Error message

agent command is only available in server mode

What it means

AgentCmd.Run guards on args.Mode: the agent subcommand (gRPC agent on port 7007 for remote hosts) only makes sense when the process is running in server mode. Any other mode returns this fixed error without creating clients or certificates.

Solutions

1. Run with mode=server (default) when using the agent subcommand
2. Remove or fix the DOZZLE_MODE environment variable that forces another mode
3. For swarm/k8s deployments, use the built-in discovery instead of the standalone agent command
4. If launching agent nodes, start them as plain server-mode processes with `dozzle agent`

Example fix

// before
DOZZLE_MODE=k8s dozzle agent   # error: only server mode
// after
dozzle agent                   # server mode (default), agent starts on :7007

if mode != "server" {
    return fmt.Errorf("agent requires server mode, got %q", mode)
}

if err := agentCmd.Run(args, certs); err != nil {
    if strings.Contains(err.Error(), "only available in server mode") {
        log.Fatal("start with mode=server or drop DOZZLE_MODE")
    }
}

When it happens

Trigger: Invoking the agent command while args.Mode is "swarm", "k8s", "agent", or anything other than "server".

Common situations: Running `dozzle agent` with DOZZLE_MODE=k8s or a swarm-mode deployment; startup scripts exporting a mode env var that conflicts with the intended agent mode; copy-pasted launch commands.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• failed to parse certificate
• failed to connect to
• invalid agent endpoint
• 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/cf5a1fe33f9e11de. Report an issue: GitHub.

Appendix: source

Thrown at internal/support/cli/agent_command.go:143

	} else {
		log.Debug().Msg("Persisted cloud.yml on agent")
	}
}

func (h *persistingNotificationHandler) ClearCloudDispatcher() {
	h.manager.ClearCloudDispatcher()
	h.cloudConfig.Store(nil)
	if h.onCloudSet != nil {
		h.onCloudSet()
	}
	if err := os.Remove("./data/cloud.yml"); err != nil && !os.IsNotExist(err) {
		log.Error().Err(err).Msg("Could not remove cloud.yml on agent")
	}
}

func (a *AgentCmd) Run(args Args, embeddedCerts embed.FS) error {
	if args.Mode != "server" {
		return fmt.Errorf("agent command is only available in server mode")
	}
	client, err := docker.NewLocalClient(args.Hostname)
	if err != nil {
		return fmt.Errorf("failed to create docker client: %w", err)
	}
	certs, err := ReadCertificates(embeddedCerts, args.CertPath, args.KeyPath)
	if err != nil {
		return fmt.Errorf("failed to read certificates: %w", err)
	}

	listener, err := net.Listen("tcp", args.Agent.Addr)
	if err != nil {
		return fmt.Errorf("failed to listen: %w", err)
	}
	const agentAddrFile = "/tmp/dozzle-agent.addr"
	if err := os.WriteFile(agentAddrFile, []byte(args.Agent.Addr), 0644); err != nil {
		return fmt.Errorf("failed to write agent address file: %w", err)
	}

View on GitHub (pinned to d9463cbe21)