{"record":{"id":"e64c1879fe791f88","repo":"joewalnes/websocketd","slug":"unable-to-locate-specified-command-s-in-os-path","errorCode":null,"errorMessage":"unable to locate specified COMMAND '%s' in OS path","messagePattern":"unable to locate specified COMMAND '(.+?)' in OS path","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config.go","lineNumber":205,"sourceCode":"\t\tif v := os.Getenv(key); v != \"\" {\n\t\t\tif clean := strings.TrimSpace(newlineCleaner.Replace(v)); clean != \"\" {\n\t\t\t\tenv = append(env, fmt.Sprintf(\"%s=%s\", key, clean))\n\t\t\t}\n\t\t}\n\t}\n\treturn env\n}\n\n// resolveCommand validates and resolves the command to execute.\n// Returns the resolved command path and arguments.\nfunc resolveCommand(args []string, scriptDir string) (commandName string, commandArgs []string, err error) {\n\tif len(args) > 0 {\n\t\tif scriptDir != \"\" {\n\t\t\treturn \"\", nil, fmt.Errorf(\"ambiguous: provided COMMAND and --dir argument, please only specify one\")\n\t\t}\n\t\tpath, lookErr := exec.LookPath(args[0])\n\t\tif lookErr != nil {\n\t\t\treturn \"\", nil, fmt.Errorf(\"unable to locate specified COMMAND '%s' in OS path\", args[0])\n\t\t}\n\t\treturn path, args[1:], nil\n\t}\n\treturn \"\", nil, nil\n}\n\n// resolveScriptDir validates and resolves the script directory path.\nfunc resolveScriptDir(dir string) (string, error) {\n\tif dir == \"\" {\n\t\treturn \"\", nil\n\t}\n\tabsDir, err := filepath.Abs(dir)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"could not resolve absolute path to dir '%s'\", dir)\n\t}\n\tinf, err := os.Stat(absDir)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"could not find your script dir '%s'\", dir)","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/joewalnes/websocketd/blob/7a8683dc7f9778dc615945aaed2a8dc77290227b/config.go#L187-L223","documentation":"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.","triggerScenarios":"`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`.","commonSituations":"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.","solutions":["Use an absolute or relative path to the command: `websocketd ./count.sh`","Install the missing interpreter/binary or fix PATH so it is findable (PATH must include its directory; '.' is not implicitly searched)","Verify the exact binary name with `command -v <name>` (e.g. use `node` vs `nodejs` per distro)"],"exampleFix":"// before\nwebsocketd count.sh --port=8080\n// after\nwebsocketd ./count.sh --port=8080   # or: export PATH=\"$PWD:$PATH\"","handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"count.sh\"); err != nil {\n\tlog.Fatalf(\"command not on PATH: %v\", err)\n}\nexec.Command(\"websocketd\", \"count.sh\", \"--port=8080\").Run()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use absolute/relative script paths instead of bare names","Run `command -v <cmd>` before launching in deploy scripts","Ensure the interpreter exists in container images (install python3/node etc.)","Remember PATH does not include the current directory"],"tags":["cli","exec","path","command-not-found"],"backgroundTag":"command-not-found-on-path","analyzedSha":"7a8683dc7f9778dc615945aaed2a8dc77290227b","analyzedAt":"2026-09-03T13:52:22.309Z","contentChangedAt":"2026-09-03T13:52:22.309Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}