XTLS/Xray-core · error

failed to open

Error message

failed to open 

What it means

Wrapped error (message continues with the file path; underlying error attached via .Base) from checkFile when filesystem.OpenAsset cannot open the geodata file (geoip.dat / geosite.dat). OpenAsset resolves the asset location from XRAY_LOCATION_ASSET / XRAY_LOCATION_ASSET_CONF or platform defaults; failure means the file is missing or unreadable at that resolved path.

Source

Thrown at common/geodata/geodat_loader.go:19

package geodata

import (
	"bufio"
	"bytes"
	"io"
	"runtime"
	"strings"

	"github.com/xtls/xray-core/common/errors"
	"github.com/xtls/xray-core/common/platform/filesystem"

	"google.golang.org/protobuf/proto"
)

func checkFile(file, code string) error {
	r, err := filesystem.OpenAsset(file)
	if err != nil {
		return errors.New("failed to open ", file).Base(err)
	}
	defer r.Close()
	if _, err := find(r, []byte(code), false); err != nil {
		return errors.New("failed to check code ", code, " from ", file).Base(err)
	}
	return nil
}

func loadFile(file, code string) ([]byte, error) {
	runtime.GC() // peak mem
	r, err := filesystem.OpenAsset(file)
	if err != nil {
		return nil, errors.New("failed to open ", file).Base(err)
	}
	defer r.Close()
	bs, err := find(r, []byte(code), true)
	if err != nil {
		return nil, errors.New("failed to load code ", code, " from ", file).Base(err)

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Download the official geoip.dat and geosite.dat (e.g. from v2fly domain-list-community / geoip releases) into the resolved asset directory shown in the error path.
2. Set XRAY_LOCATION_ASSET to the directory that actually contains the dat files and restart.
3. Check file permissions (readable by the xray process user) and that the filename matches exactly, including case.

Example fix

# before
$ XRAY_LOCATION_ASSET=/opt/xray/assets xray run -c config.json
# error: failed to open /opt/xray/assets/geosite.dat

# after
$ ls /opt/xray/assets # confirm files; if absent:
$ wget -O /opt/xray/assets/geosite.dat https://github.com/v2fly/domain-list-community/releases/latest/download/dlc.dat
$ wget -O /opt/xray/assets/geoip.dat https://github.com/v2fly/geoip/releases/latest/download/geoip.dat

f, err := os.Open(filepath.Join(assetDir, "geosite.dat"))
if err != nil { /* download or fix XRAY_LOCATION_ASSET before start */ }
f.Close()

err := checkFile("geosite.dat", "cn")
if err != nil { log.Fatal(err) /* surface asset path problem to operator */ }

When it happens

Trigger: checkFile(file, code) — invoked when Xray starts with geoip/geosite rules — and the resolved asset path contains no such file: fresh installs that never downloaded dat files, wrong XRAY_LOCATION_ASSET, or unreadable permissions on the dat file.

Common situations: Running xray from a directory without geosite.dat while the config uses geosite:cn-style routing; Docker images or systemd units where the asset env var points elsewhere; dat file owned by root with mode 600 under a different user.

Related errors

• empty domain rule list
• unknown domain type:
• failed to check code
• failed to load code
• failed to build IPv4 set

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/0832e56251193ad3. Report an issue: GitHub.