{"record":{"id":"df4d37ee7b7a2d07","repo":"XTLS/Xray-core","slug":"failed-to-create-server","errorCode":null,"errorMessage":"failed to create server","messagePattern":"failed to create server","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"main/run.go","lineNumber":226,"sourceCode":"func getConfigFormat() string {\n\tf := core.GetFormatByExtension(*format)\n\tif f == \"\" {\n\t\tf = \"auto\"\n\t}\n\treturn f\n}\n\nfunc startXray() (core.Server, error) {\n\tconfigFiles := getConfigFilePath(true)\n\n\tc, err := core.LoadConfig(getConfigFormat(), configFiles)\n\tif err != nil {\n\t\treturn nil, errors.New(\"failed to load config files: [\", configFiles.String(), \"]\").Base(err)\n\t}\n\n\tserver, err := core.New(c)\n\tif err != nil {\n\t\treturn nil, errors.New(\"failed to create server\").Base(err)\n\t}\n\n\treturn server, nil\n}\n","sourceCodeStart":208,"sourceCodeEnd":231,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/main/run.go#L208-L231","documentation":"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).","triggerScenarios":"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).","commonSituations":"Upgrading Xray versions where a protocol was renamed/removed but config still references it; feature/policy misconfiguration; running two instances where handlers collide.","solutions":["Read the chained Base(err): it names the feature/handler that failed to initialize","Check every \"protocol\" field value against the protocols supported by your Xray build (xray help / docs)","Validate the config semantically before boot (parse + build in a test harness)","After upgrades, migrate config keys per the release notes of the new version"],"exampleFix":"// before\n{\"outbounds\":[{\"protocol\":\"blackhole2\",\"tag\":\"block\"}]} // unregistered -> failed to create server\n\n// after\n{\"outbounds\":[{\"protocol\":\"blackhole\",\"tag\":\"block\"}]}","handlingStrategy":"try-catch","validationCode":"// dry build: load + build the config object in isolation before daemonizing\nc, err := core.LoadConfig(\"json\", nil, cmdarg.Arg{path}); if err != nil { return err }\nif _, err := core.New(c); err != nil { return fmt.Errorf(\"config would fail to create server: %w\", err) }","typeGuard":null,"tryCatchPattern":"if _, err := startXray(); err != nil {\n    if strings.Contains(err.Error(), \"failed to create server\") { printBaseCauseAndExit(err) }\n}","preventionTips":["Validate protocol names against the build's registered handlers before deploy","Smoke-test boot in a staging container after every config or version change","Read release notes on upgrades for renamed/removed protocols"],"tags":["go","xray","startup","server-init","config"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}