{"record":{"id":"cf5a1fe33f9e11de","repo":"amir20/dozzle","slug":"agent-command-is-only-available-in-server-mode","errorCode":null,"errorMessage":"agent command is only available in server mode","messagePattern":"agent command is only available in server mode","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/support/cli/agent_command.go","lineNumber":143,"sourceCode":"\t} else {\n\t\tlog.Debug().Msg(\"Persisted cloud.yml on agent\")\n\t}\n}\n\nfunc (h *persistingNotificationHandler) ClearCloudDispatcher() {\n\th.manager.ClearCloudDispatcher()\n\th.cloudConfig.Store(nil)\n\tif h.onCloudSet != nil {\n\t\th.onCloudSet()\n\t}\n\tif err := os.Remove(\"./data/cloud.yml\"); err != nil && !os.IsNotExist(err) {\n\t\tlog.Error().Err(err).Msg(\"Could not remove cloud.yml on agent\")\n\t}\n}\n\nfunc (a *AgentCmd) Run(args Args, embeddedCerts embed.FS) error {\n\tif args.Mode != \"server\" {\n\t\treturn fmt.Errorf(\"agent command is only available in server mode\")\n\t}\n\tclient, err := docker.NewLocalClient(args.Hostname)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create docker client: %w\", err)\n\t}\n\tcerts, err := ReadCertificates(embeddedCerts, args.CertPath, args.KeyPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to read certificates: %w\", err)\n\t}\n\n\tlistener, err := net.Listen(\"tcp\", args.Agent.Addr)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to listen: %w\", err)\n\t}\n\tconst agentAddrFile = \"/tmp/dozzle-agent.addr\"\n\tif err := os.WriteFile(agentAddrFile, []byte(args.Agent.Addr), 0644); err != nil {\n\t\treturn fmt.Errorf(\"failed to write agent address file: %w\", err)\n\t}","sourceCodeStart":125,"sourceCodeEnd":161,"githubUrl":"https://github.com/amir20/dozzle/blob/d9463cbe21874e44ab79db6fa63e746ca7d22928/internal/support/cli/agent_command.go#L125-L161","documentation":"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.","triggerScenarios":"Invoking the agent command while args.Mode is \"swarm\", \"k8s\", \"agent\", or anything other than \"server\".","commonSituations":"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.","solutions":["Run with mode=server (default) when using the agent subcommand","Remove or fix the DOZZLE_MODE environment variable that forces another mode","For swarm/k8s deployments, use the built-in discovery instead of the standalone agent command","If launching agent nodes, start them as plain server-mode processes with `dozzle agent`"],"exampleFix":"// before\nDOZZLE_MODE=k8s dozzle agent   # error: only server mode\n// after\ndozzle agent                   # server mode (default), agent starts on :7007","handlingStrategy":"validation","validationCode":"if mode != \"server\" {\n    return fmt.Errorf(\"agent requires server mode, got %q\", mode)\n}","typeGuard":null,"tryCatchPattern":"if err := agentCmd.Run(args, certs); err != nil {\n    if strings.Contains(err.Error(), \"only available in server mode\") {\n        log.Fatal(\"start with mode=server or drop DOZZLE_MODE\")\n    }\n}","preventionTips":["Check DOZZLE_MODE / --mode before launching the agent subcommand","Use swarm/k8s built-in discovery instead of the agent in those modes","Document the server-mode requirement in launch scripts"],"tags":["cli","agent","mode-validation"],"backgroundTag":"unsupported-operation","analyzedSha":"d9463cbe21874e44ab79db6fa63e746ca7d22928","analyzedAt":"2026-09-07T10:08:55.855Z","contentChangedAt":"2026-09-07T10:08:55.855Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}