joewalnes/websocketd · error

unable to locate specified COMMAND '%s' in OS path

Error message

unable to locate specified COMMAND '%s' in OS path

What it means

resolveCommand calls exec.LookPath on the first positional argument; when the OS cannot find that executable in any PATH directory, the CLI reports this error instead of starting the server. It is a fail-fast validation of the launch target, thrown before any WebSocket listener is created.

Source

Thrown at config.go:205

		if v := os.Getenv(key); v != "" {
			if clean := strings.TrimSpace(newlineCleaner.Replace(v)); clean != "" {
				env = append(env, fmt.Sprintf("%s=%s", key, clean))
			}
		}
	}
	return env
}

// resolveCommand validates and resolves the command to execute.
// Returns the resolved command path and arguments.
func resolveCommand(args []string, scriptDir string) (commandName string, commandArgs []string, err error) {
	if len(args) > 0 {
		if scriptDir != "" {
			return "", nil, fmt.Errorf("ambiguous: provided COMMAND and --dir argument, please only specify one")
		}
		path, lookErr := exec.LookPath(args[0])
		if lookErr != nil {
			return "", nil, fmt.Errorf("unable to locate specified COMMAND '%s' in OS path", args[0])
		}
		return path, args[1:], nil
	}
	return "", nil, nil
}

// resolveScriptDir validates and resolves the script directory path.
func resolveScriptDir(dir string) (string, error) {
	if dir == "" {
		return "", nil
	}
	absDir, err := filepath.Abs(dir)
	if err != nil {
		return "", fmt.Errorf("could not resolve absolute path to dir '%s'", dir)
	}
	inf, err := os.Stat(absDir)
	if err != nil {
		return "", fmt.Errorf("could not find your script dir '%s'", dir)

View on GitHub (pinned to 7a8683dc7f)

Solutions

1. Use an absolute or relative path to the command: `websocketd ./count.sh`
2. Install the missing interpreter/binary or fix PATH so it is findable (PATH must include its directory; '.' is not implicitly searched)
3. Verify the exact binary name with `command -v <name>` (e.g. use `node` vs `nodejs` per distro)

Example fix

// before
websocketd count.sh --port=8080
// after
websocketd ./count.sh --port=8080   # or: export PATH="$PWD:$PATH"

if _, err := exec.LookPath("count.sh"); err != nil {
	log.Fatalf("command not on PATH: %v", err)
}
exec.Command("websocketd", "count.sh", "--port=8080").Run()

When it happens

Trigger: `websocketd count.sh` where count.sh is not on PATH; `websocketd python3 --version` on an image without python3; a typo like `websocketd nodejs` on systems that install `node`.

Common situations: Missing interpreter in minimal Docker images; scripts present in the current directory but not on PATH (PATH does not include '.'); CI runners where the tool was installed into a non-PATH prefix; renamed binaries across OS distributions.

Related errors

• could not resolve absolute path to dir '%s'
• --socketmode %q is not an octal permission mode (e.g. 0700)
• --socketmode %q has bits beyond permission bits (keep it wit
• --socketmode 0 would make the socket unusable; pick a mode l
• please specify both --sslcert and --sslkey when requesting -

AI-assisted analysis of joewalnes/websocketd@7a8683dc7f (2026-09-03). Data as JSON: /api/errors/e64c1879fe791f88. Report an issue: GitHub.