XTLS/Xray-core · error

failed to check code

Error message

failed to check code 

What it means

Wrapped error from checkFile when the dat file opened fine but the find() scanner could not locate the requested code header (e.g. 'cn', 'google') while scanning the protobuf stream in verify mode (readBody=false). The base error carries the underlying cause — typically io.ErrUnexpectedEOF/EOF from a truncated or structurally invalid dat file, or the code simply not existing in that file.

Source

Thrown at common/geodata/geodat_loader.go:23

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

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Correct the code in the routing rule to one present in your dat file (check the geosite code list for your dat source).
2. Replace the dat file with the full official release (v2fly) and retry — truncation also produces this.
3. If using custom dat files, regenerate them including the codes your config references.

Example fix

// before (config)
{"type": "field", "outboundTag": "direct", "domain": ["geosite:China"]}

// after
{"type": "field", "outboundTag": "direct", "domain": ["geosite:cn"]}

// Startup smoke check for every geosite/geoip code your config uses:
for _, code := range neededCodes {
    if err := checkFile("geosite.dat", code); err != nil { /* fix code or dat before serving */ }
}

if err := checkFile(file, code); err != nil {
    if strings.Contains(err.Error(), "failed to check code") { /* code missing/truncated: fix dat or code */ }
}

When it happens

Trigger: checkFile('geosite.dat', code) where code is absent (typo like 'China' instead of 'cn', or a code only present in an extended dat) or where the file is truncated so the header never matches.

Common situations: Routing rules using a geosite/geoip code that the shipped dat does not contain (regional codes, 'geolocation-!cn' variants on minimal dat files); partially downloaded dat files; custom condensed dat files stripped of many codes.

Related errors

• no valid ip matcher
• balancing strategy returns empty tag
• empty domain rule list
• unknown domain type:
• failed to open

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