joewalnes/websocketd · error

script not found

Error message

script not found

What it means

ErrScriptNotFound is the sentinel error returned when websocketd cannot resolve a request path to an executable script. The handler requires the URL path to start with '/', the path must parse, and a matching script must exist under the configured --dir/scriptdir; any failure maps to this single sentinel.

Source

Thrown at libwebsocketd/handler.go:24

package libwebsocketd

import (
	"crypto/rand"
	"encoding/hex"
	"errors"
	"fmt"
	"net"
	"net/http"
	"os"
	"path/filepath"
	"strconv"
	"strings"
	"time"

	"github.com/gorilla/websocket"
)

var ErrScriptNotFound = errors.New("script not found")

// WebsocketdHandler is a single request information and processing structure, it handles WS requests out of all that daemon can handle (static, cgi, devconsole)
type WebsocketdHandler struct {
	server *WebsocketdServer

	Id string
	*RemoteInfo
	*URLInfo
	Env []string

	command string
}

// NewWebsocketdHandler constructs the struct and parses all required things in it...
func NewWebsocketdHandler(s *WebsocketdServer, req *http.Request, log *LogScope) (wsh *WebsocketdHandler, err error) {
	wsh = &WebsocketdHandler{server: s, Id: generateId()}
	log.Associate("id", wsh.Id)

View on GitHub (pinned to 7a8683dc7f)

Solutions

1. Check the WebSocket URL path matches the script filename relative to the script directory
2. Verify the script exists and is executable in the directory passed via --dir
3. Ensure the client URL path starts with '/'
4. If mapping paths yourself, confirm the path is non-empty and begins with '/' before calling GetURLInfo

Example fix

// before
ws://host:8080/
// after
ws://host:8080/myscript.js  (where ./myscript.js exists in the script dir)

// client-side check before connecting
if (!path.startsWith('/')) throw new Error('path must start with /');
const res = await fetch('http://host:8080' + path, {method:'HEAD'});
if (!res.ok) throw new Error('script not found at ' + path);

const ws = new WebSocket(url);
ws.onerror = (e) => console.error('script not found — verify path and --dir:', url);

When it happens

Trigger: GetURLInfo (libwebsocketd/handler.go:140) when the request path is empty or does not begin with '/'; handler.go:154 when http url parsing of the path fails; serveWebSocket when no matching script file is found in the script directory.

Common situations: Requesting the bare root path '/' or an empty path; typo in the script name in the WebSocket URL; script placed outside the configured script directory; client connecting to a path that maps to a non-executable or missing file.

Related errors

• too many forks active
• --maxframesize must not be negative; use 0 for unlimited
• same origin policy violated
• origin list matches were not found
• 500 Internal Server Error

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