yudai/gotty · error

failed to read custom index file at `%s`

Error message

failed to read custom index file at `%s`

What it means

Wrapped ioutil.ReadFile error in Server.New when --index-file is set: the custom index page at the expanded path cannot be read (missing file, bad ~ expansion, or permission denied). Startup aborts because the fallback embedded index is intentionally not used.

Source

Thrown at server/server.go:47

	options *Options

	upgrader      *websocket.Upgrader
	indexTemplate *template.Template
	titleTemplate *noesctmpl.Template
}

// New creates a new instance of Server.
// Server will use the New() of the factory provided to handle each request.
func New(factory Factory, options *Options) (*Server, error) {
	indexData, err := Asset("static/index.html")
	if err != nil {
		panic("index not found") // must be in bindata
	}
	if options.IndexFile != "" {
		path := homedir.Expand(options.IndexFile)
		indexData, err = ioutil.ReadFile(path)
		if err != nil {
			return nil, errors.Wrapf(err, "failed to read custom index file at `%s`", path)
		}
	}
	indexTemplate, err := template.New("index").Parse(string(indexData))
	if err != nil {
		panic("index template parse failed") // must be valid
	}

	titleTemplate, err := noesctmpl.New("title").Parse(options.TitleFormat)
	if err != nil {
		return nil, errors.Wrapf(err, "failed to parse window title format `%s`", options.TitleFormat)
	}

	var originChekcer func(r *http.Request) bool
	if options.WSOrigin != "" {
		matcher, err := regexp.Compile(options.WSOrigin)
		if err != nil {
			return nil, errors.Wrapf(err, "failed to compile regular expression of Websocket Origin: %s", options.WSOrigin)
		}

View on GitHub (pinned to a080c85cbc)

Solutions

1. Check the path exists and is readable by the server user
2. Verify homedir expansion produced the intended absolute path
3. Point --index-file at an absolute path to avoid ~ expansion surprises

When it happens

Trigger: Thrown at server/server.go:47 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of yudai/gotty@a080c85cbc (2026-09-02). Data as JSON: /api/errors/46df6e06db0ab4a8. Report an issue: GitHub.