XTLS/Xray-core · error · errors.Error

failed to decode config: {arg}

Error message

failed to decode config: {arg}

What it means

The YAML loader read the input but serial.DecodeYAMLConfig failed to unmarshal it into Xray's *conf.Config structure. Covers YAML syntax errors (bad indentation, tabs, unquoted special characters) and type/structure mismatches; the decoder message with line numbers is chained as the Base cause.

Source

Thrown at main/yaml/yaml.go:32

)

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. Validate with a YAML linter (yamllint, online parsers) to get exact line of the syntax error
2. Quote ambiguous scalars; ensure ports are plain integers, booleans are true/false
3. Indent with spaces only, consistently 2 per level; no tabs anywhere
4. Cross-check top-level keys (inbounds, outbounds, routing, ...) against the schema

Example fix

# before
inbounds:
  - port: "443"
    protocol: dokodemo-door

# after
inbounds:
  - port: 443
    protocol: dokodemo-door

import "gopkg.in/yaml.v3"
var v map[string]interface{}
if err := yaml.Unmarshal(data, &v); err != nil { log.Fatalf("yaml syntax: %v", err) } // run before xray

if err := loadYaml(); err != nil {
    var typ *yaml.TypeError
    if errors.As(err, &typ) { for _, line := range typ.Line { report(line) } }
}

When it happens

Trigger: Tabs used for indentation (YAML forbids them), port as quoted string where an int is required, duplicated keys, or mapping structure that does not match the config schema.

Common situations: Hand-indenting nested inbounds/settings and misaligning by one space; unquoted 'on'/'no'/'443:' style scalars parsed as wrong YAML types; copying JSON-shaped structure into YAML without converting braces to indentation.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to decode config:
• failed to decode config: {arg}
• failed to read 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/96c97be911f1da91. Report an issue: GitHub.