What causes "failed to load config files: [" in XTLS/Xray-core?

Look at the chained Base(err) — it points at the exact file and parse/read failure (errors 544/545/549-552)

failed to load config files: [

Error message

failed to load config files: [

What it means

Top-level wrapper thrown by startXray in main/run.go when core.LoadConfig fails for the collected config file list. It aggregates every per-format failure: unreadable files, JSON/TOML/YAML decode errors, and multi-file merge errors from Config.Override. The message includes the full file list and the real cause is chained via Base(err), so the underlying loader error must be read to diagnose.

Source

Thrown at main/run.go:221

		log.Println("Using config from STDIN")
	}
	return cmdarg.Arg{"stdin:"}
}

func getConfigFormat() string {
	f := core.GetFormatByExtension(*format)
	if f == "" {
		f = "auto"
	}
	return f
}

func startXray() (core.Server, error) {
	configFiles := getConfigFilePath(true)

	c, err := core.LoadConfig(getConfigFormat(), configFiles)
	if err != nil {
		return nil, errors.New("failed to load config files: [", configFiles.String(), "]").Base(err)
	}

	server, err := core.New(c)
	if err != nil {
		return nil, errors.New("failed to create server").Base(err)
	}

	return server, nil
}

View on GitHub (pinned to 7d214f8b09)

Solutions

Look at the chained Base(err) — it points at the exact file and parse/read failure (errors 544/545/549-552)
Run xjson-style validation or xray run -test (if available in your build) to dry-check config
Ensure the -format flag matches the file content, or omit it to use auto-detection by extension
When using multiple configs, verify the later files only override compatible fields

Example fix

# before
xray run -format json -c /etc/xray/config.yaml  # yaml parsed as json -> failed to load config files

# after
xray run -c /etc/xray/config.yaml  # auto-detect by .yaml extension

Defensive patterns

Strategy: try-catch

Validate before calling

// fail fast before start
for _, p := range getConfigFilePaths() {
    if _, err := os.Stat(p); err != nil { return err }
}

Try / catch

if server, err := startXray(); err != nil {
    log.Fatalf("startup failed: %v", err) // Base(err) names the real file/line cause
}

Prevention

Add a config validation stage (parse all files with the matching loader) to deploy scripts
Keep -format consistent with file extensions or omit it
Pin config schema to your Xray version in docs

When it happens

Trigger: Any xray run / xray -c invocation where at least one config file cannot be read, parsed, or merged: missing file, syntax error, or conflicting settings between multiple -c files during Override.

Common situations: Booting the Xray daemon with a broken config after an edit; passing several configs where a later one overrides incompatibly; wrong -format flag (e.g. forcing json on a yaml file).

Related errors

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