XTLS/Xray-core · error

asset is not a regular file

Error message

asset is not a regular file

What it means

Returned after os.Stat succeeds but the target inside the asset directory is not a regular file: it is a directory, symlink to something irregular, device, socket, etc. The asset resolver only serves plain files.

Source

Thrown at common/platform/filesystem/file.go:69

	path, _, err := getAssetFileLocation(file)
	return path, err
}

func getAssetFileLocation(file string) (string, os.FileInfo, error) {
	if !filepath.IsLocal(file) || file == "." {
		return "", nil, errors.New("asset path must stay in asset directory")
	}
	local, err := filepath.Localize(file)
	if err != nil {
		return "", nil, err
	}
	path := platform.GetAssetLocation(local)
	info, err := os.Stat(path)
	if err != nil {
		return "", nil, err
	}
	if !info.Mode().IsRegular() {
		return "", nil, errors.New("asset is not a regular file")
	}
	return path, info, nil
}

func ReadCert(file string) ([]byte, error) {
	if filepath.IsAbs(file) {
		return ReadFile(file)
	}
	return ReadFile(platform.GetCertLocation(file))
}

func CopyFile(dst string, src string) error {
	bytes, err := ReadFile(src)
	if err != nil {
		return err
	}
	f, err := os.OpenFile(dst, os.O_CREATE|os.O_WRONLY, 0o644)
	if err != nil {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Check with ls/file that the asset entry is a regular file and replace any directory with the real file
2. Remove symlinks pointing at non-regular targets inside the asset directory
3. Re-download the asset (e.g. geodata files) so a plain file exists at the expected name

Example fix

# replace a mistakenly-created directory with the real asset file
rm -rf /usr/local/share/xray/geosite.dat
cp geosite.dat /usr/local/share/xray/geosite.dat

if info, err := os.Stat(assetPath); err == nil && !info.Mode().IsRegular() {
    return errors.New("asset is a directory/special file; replace with the real file")
}

When it happens

Trigger: Calling ResolveAsset/StatAsset with a name that resolves to a subdirectory (e.g. 'subdir') or a special file inside the asset location.

Common situations: Users creating a directory named like the expected asset (e.g. a 'geosite' folder), or symlinks inside the asset dir pointing at fifos/devices; misconfigured downloads that create directories.

Related errors

• asset path must stay in asset directory
• invalid geodata asset file:
• both file and bytes are empty.
• not a Service.
• Dispatcher: Invalid destination.

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