micro/go-micro · critical

failed to start agent: %w

Error message

failed to start agent: %w

What it means

When starting the agent's embedded server (Run/serve path, agent/agent.go:634), server.Start() failures are wrapped as 'failed to start agent: %w'. This usually means the transport/port setup failed, so the agent never becomes callable.

Source

Thrown at agent/agent.go:634

	serverOpts := []server.Option{
		server.Name(a.opts.Name),
		server.Address(a.opts.Address),
		server.Registry(a.opts.Registry),
		server.Metadata(map[string]string{
			"type":     "agent",
			"services": strings.Join(a.opts.Services, ","),
		}),
	}
	if a.opts.Broker != nil {
		serverOpts = append(serverOpts, server.Broker(a.opts.Broker))
	}
	a.server = server.NewServer(serverOpts...)

	_ = pb.RegisterAgentHandler(a.server, a)

	if err := a.server.Start(); err != nil {
		return fmt.Errorf("failed to start agent: %w", err)
	}

	stopCh := make(chan struct{})
	a.mu.Lock()
	a.stopCh = stopCh
	a.mu.Unlock()

	fmt.Printf("Agent %s registered (manages: %s)\n", a.opts.Name, strings.Join(a.opts.Services, ", "))

	// Optionally serve the agent directly over the A2A protocol, calling
	// Ask in-process — no separate gateway needed to be queried by URL.
	if a.opts.A2AAddress != "" {
		card := a2a.Card(a.opts.Name, "http://localhost"+a.opts.A2AAddress, "", a.opts.Services)
		handler := a2a.NewAgentStreamHandler(card, func(ctx context.Context, text string) (string, error) {
			resp, err := a.Ask(ctx, text)
			if err != nil {
				return "", err
			}

View on GitHub (pinned to 24529f1404)

Solutions

1. Read the wrapped error to identify the concrete server failure
2. Check that the configured address/port is free (lsof/netstat) and change it if taken
3. Validate server Options (transport, address, TLS settings) passed to the agent
4. Run with elevated privileges or a port >1024 if binding is permission-denied
5. Check for a stale previous instance still holding the port and stop it

Example fix

// before
agent.Run(ctx) // binds :8080, fails: address in use
// after
srvOpts := []server.Option{server.Address(":8081")}
ag := agent.New(..., agent.ServerOptions(srvOpts...))
agent.Run(ctx)

// before starting, ensure the port is free
ln, err := net.Listen("tcp", addr)
if err != nil { return fmt.Errorf("address %s unavailable: %w", addr, err) }
ln.Close()

if err := ag.Run(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to start agent") {
        log.Printf("agent server failed: %v", errors.Unwrap(err))
        // pick a different port or fix transport config, then restart
    }
    return err
}

When it happens

Trigger: Calling the agent's run/serve entry point when the underlying micro server fails to start: port already in use, invalid transport/address options, or transport initialization errors.

Common situations: Port conflicts with another process, bad --address/transport flags or env config, missing permissions to bind the port, misconfigured TLS for the server transport.

Related errors

• agent: StreamAsk unsupported by implementation
• agent: ResumeStreamAsk unsupported by implementation
• agent: ResumeStreamAsk requires a checkpoint
• agent: checkpointed run not found
• agent: checkpointed run is terminal with status

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/5d8ae012e2fe8e09. Report an issue: GitHub.