{"record":{"id":"e2ff7e88a1dda31f","repo":"XTLS/Xray-core","slug":"failed-to-read-system-hosts","errorCode":null,"errorMessage":"failed to read system hosts","messagePattern":"failed to read system hosts","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"infra/conf/dns.go","lineNumber":373,"sourceCode":"\t\tns, err := server.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"failed to build nameserver\").Base(err)\n\t\t}\n\t\tns.PolicyID = buildPolicyID(server)\n\t\tconfig.NameServer = append(config.NameServer, ns)\n\t}\n\n\tif c.Hosts != nil {\n\t\tstaticHosts, err := c.Hosts.Build()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"failed to build hosts\").Base(err)\n\t\t}\n\t\tconfig.StaticHosts = append(config.StaticHosts, staticHosts...)\n\t}\n\tif c.UseSystemHosts {\n\t\tsystemHosts, err := readSystemHosts()\n\t\tif err != nil {\n\t\t\treturn nil, errors.New(\"failed to read system hosts\").Base(err)\n\t\t}\n\t\tconfig.StaticHosts = append(config.StaticHosts, systemHosts...)\n\t}\n\n\treturn config, nil\n}\n\nfunc resolveQueryStrategy(queryStrategy string) dns.QueryStrategy {\n\tswitch strings.ToLower(queryStrategy) {\n\tcase \"useip\", \"use_ip\", \"use-ip\":\n\t\treturn dns.QueryStrategy_USE_IP\n\tcase \"useip4\", \"useipv4\", \"use_ip4\", \"use_ipv4\", \"use_ip_v4\", \"use-ip4\", \"use-ipv4\", \"use-ip-v4\":\n\t\treturn dns.QueryStrategy_USE_IP4\n\tcase \"useip6\", \"useipv6\", \"use_ip6\", \"use_ipv6\", \"use_ip_v6\", \"use-ip6\", \"use-ipv6\", \"use-ip-v6\":\n\t\treturn dns.QueryStrategy_USE_IP6\n\tcase \"usesys\", \"usesystem\", \"use_sys\", \"use_system\", \"use-sys\", \"use-system\":\n\t\treturn dns.QueryStrategy_USE_SYS\n\tdefault:","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/infra/conf/dns.go#L355-L391","documentation":"Wrapper error from dns Config Build in infra/conf/dns.go: readSystemHosts() failed while dns.useSystemHosts is enabled. The function reads the OS hosts file (e.g. /etc/hosts); I/O or parse failures are chained with .Base(err). This is an environment-level failure, not a config syntax problem.","triggerScenarios":"\"dns\": {\"useSystemHosts\": true} on a system where /etc/hosts is unreadable (permissions), missing, or on Windows where the hosts path is absent/locked by security software.","commonSituations":"Containers with a broken /etc/hosts mount; minimal Docker images without the file; SELinux/AppArmor denying read; hosts file with exotic encoding causing parse failure.","solutions":["Check the chained base error for the OS-level cause (permission vs not-found)","Ensure /etc/hosts exists and is readable by the Xray process user","Set \"useSystemHosts\": false if system hosts are not needed"],"exampleFix":"// before\n\"dns\": {\"useSystemHosts\": true}   // in a container lacking /etc/hosts\n\n// after\n\"dns\": {\"useSystemHosts\": false, \"hosts\": {\"example.com\": \"1.2.3.4\"}}","handlingStrategy":"try-catch","validationCode":"if dnsCfg.UseSystemHosts {\n    f, err := os.Open(hostsFilePathForOS()) // \"/etc/hosts\" on unix\n    if err != nil {\n        return fmt.Errorf(\"useSystemHosts enabled but hosts file unreadable: %w\", err)\n    }\n    f.Close()\n}","typeGuard":null,"tryCatchPattern":"if _, err := dnsConf.Build(); err != nil {\n    if strings.Contains(err.Error(), \"failed to read system hosts\") {\n        // environment problem: fix permissions/mount or disable the feature\n        return errors.New(\"cannot read the OS hosts file; fix /etc/hosts or set dns.useSystemHosts to false\")\n    }\n    return err\n}","preventionTips":["In containers, mount a readable /etc/hosts or disable useSystemHosts","Check file permissions for the user running Xray","Treat this error as environmental, not a config syntax issue"],"tags":["config","dns","hosts","environment","xray"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}