XTLS/Xray-core · error

failed to load code

Error message

failed to load code 

What it means

Wrapped error from loadFile when find(..., readBody=true) locates nothing it can read a body for: after the file is open, scanning the entry stream fails — code header never matched, stream truncated mid-entry, or a decode error (EOF/unexpected EOF propagates as the Base error). Distinguished from the open failure: the file exists but its content does not yield the requested code.

Source

Thrown at common/geodata/geodat_loader.go:37

		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)
	}
	return bs, nil
}

func loadIP(file, code string) ([]*CIDR, error) {
	bs, err := loadFile(file, code)
	if err != nil {
		return nil, err
	}
	defer runtime.GC() // peak mem
	var geoip GeoIP
	if err := proto.Unmarshal(bs, &geoip); err != nil {
		return nil, errors.New("error unmarshal IP in ", file, ":", code).Base(err)
	}
	return geoip.Cidr, nil
}

func loadSite(file, code string) ([]*Domain, error) {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Re-download the dat file from the official release and verify size/checksum, then restart.
2. Confirm the requested code exists in that dat (use the check path's error or a geosite listing tool).
3. Avoid mirrors/CDNs that may serve HTML error pages; pin to GitHub release assets.

Example fix

# before
$ xray run -c config.json # geosite.dat is a truncated 12KB HTML page

# after
$ curl -L -o /etc/xray/geosite.dat https://github.com/v2fly/domain-list-community/releases/latest/download/dlc.dat
$ xray run -c config.json

// Verify dat integrity (size/checksum) before launch:
if fi, _ := os.Stat(p); fi != nil && fi.Size() < 1024*100 { /* too small: re-provision */ }

bs, err := loadFile(file, code)
if err != nil && strings.Contains(err.Error(), "failed to load code") {
    // re-download dat atomically, then retry once
}

When it happens

Trigger: loadFile('geoip.dat','cn') on a truncated or corrupted dat where the scanner hits EOF before matching the code, or the code is absent while earlier structure still parses partially.

Common situations: Interrupted downloads of dat files; dat files from mirrors that serve error pages (HTML) instead of protobuf; codes specific to extended lists missing from minimal dat files.

Related errors

• invalid body length:
• empty domain rule list
• unknown domain type:
• failed to open
• failed to check code

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