What causes "%q doesn't seem like etcd binary" in etcd-io/etcd?

Point -exec at a path that contains 'etcd', e.g. `--exec ./bin/etcd` or `--exec /usr/local/bin/etcd`.

%q doesn't seem like etcd binary

Error message

%q doesn't seem like etcd binary

What it means

etcd-dump-metrics spawns a real etcd process to scrape its /metrics, and getCommand guards that the -exec path actually looks like an etcd binary by requiring the substring "etcd" in the executable path. It panics otherwise — a deliberately crude sanity check so the tool does not launch an arbitrary unrelated executable with etcd flags.

Source

Thrown at tools/etcd-dump-metrics/etcd.go:65

	if err != nil {
		panic(err)
	}
	os.RemoveAll(cfg.Dir)

	cfg.ClusterState = "new"
	cfg.ListenClientUrls, cfg.AdvertiseClientUrls = curls, curls
	cfg.ListenPeerUrls, cfg.AdvertisePeerUrls = purls, purls

	cfg.InitialCluster = ""
	for i := range ics {
		cfg.InitialCluster += fmt.Sprintf(",%d=%s", i, ics[i].String())
	}
	cfg.InitialCluster = cfg.InitialCluster[1:]
}

func getCommand(exec, name, dir, cURL, pURL, cluster string) (args []string) {
	if !strings.Contains(exec, "etcd") {
		panic(fmt.Errorf("%q doesn't seem like etcd binary", exec))
	}
	return []string{
		exec,
		"--name", name,
		"--data-dir", dir,
		"--listen-client-urls", cURL,
		"--advertise-client-urls", cURL,
		"--listen-peer-urls", pURL,
		"--initial-advertise-peer-urls", pURL,
		"--initial-cluster", cluster,
		"--initial-cluster-token=tkn",
		"--initial-cluster-state=new",
	}
}

func write(ep string) {
	cli, err := clientv3.New(clientv3.Config{Endpoints: []string{strings.Replace(ep, "/metrics", "", 1)}})
	if err != nil {

View on GitHub (pinned to f744d457f4)

Solutions

Point -exec at a path that contains 'etcd', e.g. `--exec ./bin/etcd` or `--exec /usr/local/bin/etcd`.
If the binary must keep its name, create a symlink whose name contains etcd: `ln -s /opt/my-server ./etcd-server && --exec ./etcd-server`.
Omit -exec entirely so the tool downloads/uses a stock etcd binary (pair it with -download-ver), which always satisfies the check.

Example fix

# before
etcd-dump-metrics --exec ./bin/server ...   # panics: %q doesn't seem like etcd binary

# after
etcd-dump-metrics --exec ./bin/etcd ...
# or
ln -s ./bin/server ./bin/etcd-server && etcd-dump-metrics --exec ./bin/etcd-server ...

Defensive patterns

Strategy: validation

Validate before calling

# Validate before invoking the tool:
[ "$(basename "$EXEC_PATH")" != "${EXEC_PATH/*etcd*/}" ] || { echo "exec path must contain 'etcd'" >&2; exit 1; }

Prevention

Keep etcd binaries on paths that contain 'etcd' in the filename.
Wrap custom binaries with a symlink named *etcd* for tooling.
Prefer -download-ver over -exec when you just need metrics for a version.

When it happens

Trigger: Invoking etcd-dump-metrics with `-exec <path>` where path does not contain the literal substring "etcd" (e.g. `--exec ./bin/server` or `--exec /opt/my-binary`). The check is a plain strings.Contains, so even a valid etcd binary renamed without 'etcd' in its path fails it.

Common situations: CI or a wrapper script renames/copies the etcd binary to a neutral name; users pass a wrapper shell script as -exec; typos in the path; using a custom build artifact named differently.

Related errors

AI-assisted analysis of etcd-io/etcd@f744d457f4 (2026-08-15). Data as JSON: /api/errors/c1eaef1c31267c57. Report an issue: GitHub.