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

Error message

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

What it means

The --registry flag is matched against c.opts.Registries, populated by registry plugins via init(). A name not present means that registry implementation is not compiled into this binary, so the CLI aborts with a message directing you to import go-micro.dev/v6/cmd/defaults.

Source

Thrown at cmd/cmd.go:491

		authOpts = append(authOpts, auth.PrivateKey(ctx.String("auth_private_key")))
	}
	if len(ctx.String("auth_namespace")) > 0 {
		authOpts = append(authOpts, auth.Namespace(ctx.String("auth_namespace")))
	}
	if name := ctx.String("auth"); len(name) > 0 {
		r, ok := c.opts.Auths[name]
		if !ok {
			return fmt.Errorf("unsupported auth: %s", name)
		}

		*c.opts.Auth = r(authOpts...)
	}

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

		sopts, clopts := c.setRegistry(r())
		serverOpts = append(serverOpts, sopts...)
		clientOpts = append(clientOpts, clopts...)
	}

	// Set the debug profile
	if name := ctx.String("debug-profile"); len(name) > 0 {
		p, ok := c.opts.DebugProfiles[name]
		if !ok {
			return fmt.Errorf("unsupported profile: %s", name)
		}
		*c.opts.DebugProfile = p()
	}

	// Set the broker
	if name := ctx.String("broker"); len(name) > 0 && (*c.opts.Broker).String() != name {

View on GitHub (pinned to 24529f1404)

Solutions

Import _ "go-micro.dev/v6/cmd/defaults" (or the specific registry plugin, e.g. _ "go-micro.dev/v6/plugins/registry/etcd") and rebuild.
Verify the exact registered name (e.g. "etcd" not "etcdv3" depending on version).
Omit --registry to keep the current/default registry.
Ensure the registry server itself is irrelevant here — the error is purely about linking, not connectivity.

Example fix

// before: custom binary without plugins
micro --registry etcd server
// after: main.go
import _ "go-micro.dev/v6/cmd/defaults"
// then:
micro --registry etcd server

Defensive patterns

Strategy: validation

Validate before calling

allowedRegistries := map[string]bool{"": true, "mdns": true, "etcd": true /* linked */}
if !allowedRegistries[*registryFlag] {
    return fmt.Errorf("registry %q not linked; rebuild with cmd/defaults", *registryFlag)
}

Try / catch

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

Prevention

Ship binaries with go-micro.dev/v6/cmd/defaults imported when ops scripts use --registry.
Verify exact registry key names (e.g. "etcd" vs "etcdv3") per go-micro version.
Add deployment checks that run `micro --registry <name> --help` style validation before rollout.

When it happens

Trigger: Passing --registry etcd/consul/mdns on a binary lacking that registry plugin, or a name mismatch with the current default registry (flag is only consulted when it differs from (*c.opts.Registry).String()).

Common situations: Switching from mdns to etcd for a production deploy using a defaults-free custom binary; version upgrades where the plugin path or registered name changed; typos in the registry name.

Related errors

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