sipeed/picoclaw · error

local command %q does not exist

Error message

local command %q does not exist

What it means

For stdio servers whose target is path-like (absolute, ./, ../, contains a path separator, or starts with ~ — isLocalCommandPath, helpers.go:275-289), validateLocalCommandPath stats the file and ErrNotExist produces this error (helpers.go:314-318). Bare command names like npx or uvx are deliberately not checked; only explicit paths are verified before saving.

Source

Thrown at cmd/picoclaw/internal/mcp/helpers.go:317

	if path == "~" {
		return home
	}
	if strings.HasPrefix(path, "~/") || strings.HasPrefix(path, "~\\") {
		return filepath.Join(home, path[2:])
	}
	return path
}

func validateLocalCommandPath(command string) error {
	if !isLocalCommandPath(command) {
		return nil
	}

	path := expandHomePath(command)
	info, err := os.Stat(path)
	if err != nil {
		if errors.Is(err, os.ErrNotExist) {
			return fmt.Errorf("local command %q does not exist", command)
		}
		return fmt.Errorf("failed to stat local command %q: %w", command, err)
	}
	if info.IsDir() {
		return fmt.Errorf("local command %q is a directory", command)
	}
	if runtime.GOOS != "windows" && info.Mode()&0o111 == 0 {
		return fmt.Errorf("local command %q is not executable", command)
	}
	return nil
}

func defaultServerProbe(
	ctx context.Context,
	name string,
	server config.MCPServerConfig,
	workspacePath string,
) (probeResult, error) {

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Verify the file exists: ls -l <path> from the same directory you run picoclaw in
2. Use an absolute path or ~/ prefix so resolution does not depend on cwd
3. Build or install the binary first, then retry the add

Example fix

# before
picoclaw mcp add s ./bin/server
# after
make build && picoclaw mcp add s "$PWD/bin/server"

cmd_path=${cmd#-- }   # strip leading -- if present
if [[ $cmd_path == */* || $cmd_path == ~* || $cmd_path == .* ]]; then
  [ -e "$cmd_path" ] || { echo "command path '$cmd_path' does not exist" >&2; exit 1; }
fi
picoclaw mcp add "$name" $cmd_path

When it happens

Trigger: `picoclaw mcp add s ./build/server` when the binary was never built; `picoclaw mcp add s -- ~/tools/mcp-serve` with a typo; ~ expansion resolving against a different home directory.

Common situations: Build output path changed after a refactor; running on a second machine where the tool lives elsewhere; wrong case in the filename on case-sensitive filesystems.

Related errors

• failed to stat local command %q: %w
• local command %q is a directory
• MCP server ${server.name} requires a command.
• unsupported transport %q
• --env can only be used with stdio transport

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/62fd9d661f2203c3. Report an issue: GitHub.