XTLS/Xray-core · critical

failed to create server

Error message

failed to create server

What it means

Thrown by startXray when core.New(c) fails after the config was successfully loaded and built. core.New instantiates every inbound, outbound, router, and feature declared by the config; any handler failing to initialize (bad listener options, unknown protocol registered name, policy errors, port bind preparation) surfaces here with the cause chained in Base(err).

Source

Thrown at main/run.go:226

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

1. Read the chained Base(err): it names the feature/handler that failed to initialize
2. Check every "protocol" field value against the protocols supported by your Xray build (xray help / docs)
3. Validate the config semantically before boot (parse + build in a test harness)
4. After upgrades, migrate config keys per the release notes of the new version

Example fix

// before
{"outbounds":[{"protocol":"blackhole2","tag":"block"}]} // unregistered -> failed to create server

// after
{"outbounds":[{"protocol":"blackhole","tag":"block"}]}

// dry build: load + build the config object in isolation before daemonizing
c, err := core.LoadConfig("json", nil, cmdarg.Arg{path}); if err != nil { return err }
if _, err := core.New(c); err != nil { return fmt.Errorf("config would fail to create server: %w", err) }

if _, err := startXray(); err != nil {
    if strings.Contains(err.Error(), "failed to create server") { printBaseCauseAndExit(err) }
}

When it happens

Trigger: Config that parses but is semantically invalid: referencing an unregistered outbound protocol, inconsistent settings objects, feature registration conflicts, or an inbound whose Init fails (e.g. dokodemo with no network — error 557 surfaces through this path at server build).

Common situations: Upgrading Xray versions where a protocol was renamed/removed but config still references it; feature/policy misconfiguration; running two instances where handlers collide.

Related errors

• failed to load config files: [
• failed to get outbound handler with tag: ${tag}
• existing tag found: ${tag}
• bridge tag is empty
• bridge domain is empty

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