transport %q is not linked into this binary: import go-micro

Error message

transport %q is not linked into this binary: import go-micro.dev/v6/cmd/defaults to enable flag-selected plugins

What it means

The --transport flag is matched against c.opts.Transports, filled by transport plugins via init(). A name absent from that map means the transport is not compiled into this binary; the CLI aborts with a message pointing to go-micro.dev/v6/cmd/defaults.

Source

Thrown at cmd/cmd.go:536

	// Set the selector
	if name := ctx.String("selector"); len(name) > 0 && (*c.opts.Selector).String() != name {
		s, ok := c.opts.Selectors[name]
		if !ok {
			return fmt.Errorf("Selector %s not found", name)
		}

		*c.opts.Selector = s(selector.Registry(*c.opts.Registry))

		// No server option here. Should there be?
		clientOpts = append(clientOpts, client.Selector(*c.opts.Selector))
	}

	// Set the transport
	if name := ctx.String("transport"); len(name) > 0 && (*c.opts.Transport).String() != name {
		t, ok := c.opts.Transports[name]
		if !ok {
			return fmt.Errorf("transport %q is not linked into this binary: import go-micro.dev/v6/cmd/defaults to enable flag-selected plugins", name)
		}

		sopts, clopts := c.setTransport(t())
		serverOpts = append(serverOpts, sopts...)
		clientOpts = append(clientOpts, clopts...)

	}

	// Parse the server options
	metadata := make(map[string]string)
	for _, d := range ctx.StringSlice("server_metadata") {
		var key, val string
		parts := strings.Split(d, "=")
		key = parts[0]
		if len(parts) > 1 {
			val = strings.Join(parts[1:], "=")
		}
		metadata[key] = val

View on GitHub (pinned to 24529f1404)

Solutions

Import _ "go-micro.dev/v6/cmd/defaults" or the specific transport plugin (e.g. _ "go-micro.dev/v6/plugins/transport/quic") and rebuild.
Confirm the exact registered transport name for your go-micro version.
Omit --transport to keep the current/default transport.
Check binary imports with `go list -deps` to verify the plugin is linked.

Example fix

// before: transport not linked
micro --transport quic server
// after: main.go
import _ "go-micro.dev/v6/plugins/transport/quic"
// then:
micro --transport quic server

Defensive patterns

Strategy: validation

Validate before calling

allowedTransports := map[string]bool{"": true, "quic": true, "http": true /* linked */}
if !allowedTransports[*transportFlag] {
    return fmt.Errorf("transport %q not linked; rebuild with cmd/defaults", *transportFlag)
}

Try / catch

if err := c.Run(ctx); err != nil {
    if strings.Contains(err.Error(), "is not linked into this binary") && strings.Contains(err.Error(), "transport") {
        return fmt.Errorf("transport plugin missing: %w", err)
    }
    return err
}

Prevention

Import the transport plugin package (or cmd/defaults) in any binary accepting --transport.
Document valid transport names per build artifact.
Test flag-driven startup in CI to catch unlinked plugins before release.

When it happens

Trigger: Passing --transport quic/http (etc.) to a binary lacking the transport plugin, or a value differing from the current default transport name.

Common situations: Custom minimal builds without defaults; switching from default gRPC/mucp transport to QUIC/HTTP per docs without importing the plugin; upgrade where plugin package paths changed.

Related errors

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