XTLS/Xray-core · error · errors.Error

failed to read config: {arg}

Error message

failed to read config: {arg}

What it means

YAML counterpart of the config-read error: the YAML loader (extensions "yaml"/"yml") fails when confloader.LoadConfig cannot produce a reader for an argument. Same failure modes as errors 544/549 — missing/unreadable local file or failed http/socket fetch — with the underlying cause chained in Base(err).

Source

Thrown at main/yaml/yaml.go:28

	"github.com/xtls/xray-core/core"
	"github.com/xtls/xray-core/infra/conf"
	"github.com/xtls/xray-core/infra/conf/serial"
	"github.com/xtls/xray-core/main/confloader"
)

func init() {
	common.Must(core.RegisterConfigLoader(&core.ConfigFormat{
		Name:      "YAML",
		Extension: []string{"yaml", "yml"},
		Loader: func(input interface{}) (*core.Config, error) {
			switch v := input.(type) {
			case cmdarg.Arg:
				cf := &conf.Config{}
				for i, arg := range v {
					errors.LogInfo(context.Background(), "Reading config: ", arg)
					r, err := confloader.LoadConfig(arg)
					if err != nil {
						return nil, errors.New("failed to read config: ", arg).Base(err)
					}
					c, err := serial.DecodeYAMLConfig(r)
					if err != nil {
						return nil, errors.New("failed to decode config: ", arg).Base(err)
					}
					if i == 0 {
						// This ensure even if the muti-json parser do not support a setting,
						// It is still respected automatically for the first configure file
						*cf = *c
						continue
					}
					cf.Override(c, arg)
				}
				return cf.Build()
			case io.Reader:
				return serial.LoadYAMLConfig(v)
			default:
				return nil, errors.New("unknown type")

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Confirm the path in the message; fix extension typos (.yml vs .yaml)
2. Check read permission for the exact runtime user (sudo -u xray cat config.yml)
3. In containers, verify the volume mount actually exposes the file
4. For remote args, inspect the chained fetch error

Example fix

# before (file is config.yml, flag says config.yaml)
xray run -c /etc/xray/config.yaml

# after
xray run -c /etc/xray/config.yml

for _, p := range yamlPaths {
    if _, err := os.Stat(p); err != nil { return err }
    if data, err := os.ReadFile(p); err == nil {
        var v interface{}; if yaml.Unmarshal(data, &v) != nil { return err }
    }
}

if err := startYamlLoad(); err != nil { logPathFromMessage(err); os.Exit(1) }

When it happens

Trigger: xray run -c config.yml where the file is absent, unreadable, or where a URL-form arg could not be fetched.

Common situations: Typo between .yaml and .yml extensions, config placed outside the container volume in Docker deployments, SELinux/AppArmor denying service-user reads.

Related errors

• failed to read config:
• failed to read config:
• failed to decode config: {arg}
• failed to get outbound handler with tag: ${tag}
• existing tag found: ${tag}

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