PuppyIP Resource Center
Network & Connection Troubleshooting 10 min read Published 2026-11-17

ImmortalWrt PassWall Xray missing GeoIP or GeoSite files: check data and memory

If PassWall Xray logs report missing GeoIP or GeoSite data, check the active config path and storage before validating matching files.

ImmortalWrt PassWall Xray GeoIP geosite.dat

Service eligibility and regional restrictions

PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.

Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.

Key Takeaways

  • Missing geodata can prevent PassWall's Xray routing core from starting without indicating that the Xray binary is damaged.
  • Check only the active config's paths, filenames, nonempty files, overlay space and the precise run-test error.
  • A reduced GeoIP dataset applies only when the rules reference cn and private; other categories need a dataset that covers them.
  • Do not run an Xray config-test process alongside the active core on a low-memory router; verify wireless and UDP separately.

Confirm a data-file error before blaming the core binary

If PassWall logs explicitly report missing Geo rules and an Xray config test reports a missing data file while loading a GeoIP or GeoSite category, first inspect the data used by the active core. An exited Xray process does not prove that its binary is missing; configuration, data paths and rule categories can all prevent startup.

One historical combination was ImmortalWrt 24.10.5, PassWall 25.12.16-r1 and Xray 25.2.21. This version record bounds that observation; it is not a current recommendation or a compatibility claim for other firmware. Record the versions actually installed on the device.

Check the active config path, files and available storage

Read the active PassWall Xray configuration to find the actual GeoIP and GeoSite directory and filenames. Some OpenWrt/ImmortalWrt builds use /usr/share/v2ray/geoip.dat and geosite.dat, but a custom path or core can differ. Do not copy files to a default directory until you confirm that the running core reads it.

Check that each file exists and is nonempty, read the first Geo-related PassWall startup error and confirm that overlay space can hold the selected data. In one historical environment, the complete GeoIP and GeoSite assets exceeded available storage. Repeatedly downloading full files can fail or affect the system.

Read Geo files, logs and overlay space

sh
GEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
for name in geoip.dat geosite.dat; do
  if test -s "$GEODATA_DIR/$name"; then printf '%s present\n' "$name"; else printf '%s missing-or-empty\n' "$name"; fi
done
logread | grep -iE 'geodata|geoip|geosite|passwall|xray' | tail -n 80
df -k /overlay
Read-only shell checks on ImmortalWrt/OpenWrt. Replace the directory with the one in the active Xray config. Logs and paths may identify the device; redact before sharing.

Choose full or reduced GeoIP data from the actual rules

Check every geoip:<category> and geosite:<category> referenced by the PassWall routing rules. A reduced cn/private GeoIP dataset covers the existing rules only when the configured GeoIP categories are limited to cn and private. If rules use other country or region categories, select a matching dataset that contains them. GeoSite data must still cover the referenced domain categories.

Use filenames expected by the core: install the reduced GeoIP file under the configured geoip.dat name and the domain-rule resource as a matching geosite.dat. Match the source release and checksums to the device's PassWall/Xray versions. Do not use an unverified mirror or present an old data revision as current.

Verify the files before installing them

Choose GeoIP and GeoSite resources that cover the categories in the active rules from a trusted release by the resource maintainer. Stage the files locally and verify each SHA-256. The command below does not download files or change PassWall update settings. Only when the current rules use cn and private GeoIP categories exclusively, and the release provides a matching reduced-data update entry, change global_rules.geoip_url separately in LuCI after recording its old value. Leave the GeoSite update entry, nodes and DNS unchanged.

Before writing, stop PassWall orderly through LuCI, confirm no Xray core is active and keep wired LAN management available. Confirm the active data directory exists and overlay has room for old-file backups and temporary files. Replace every path and published checksum before running the command; it verifies the sources, backs up existing regular files, then installs and verifies the destination files. Do not run it if any source or checksum is unverified.

Verify and install the GeoIP and GeoSite files

sh
set -eu
GEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
GEOIP_SOURCE='REPLACE_WITH_VERIFIED_GEOIP_FILE'
GEOSITE_SOURCE='REPLACE_WITH_VERIFIED_GEOSITE_FILE'
EXPECTED_GEOIP_SHA256='REPLACE_WITH_PUBLISHED_GEOIP_SHA256'
EXPECTED_GEOSITE_SHA256='REPLACE_WITH_PUBLISHED_GEOSITE_SHA256'
verify_sha256() {
  printf '%s  %s\n' "$2" "$1" | sha256sum -c -
}
test -d "$GEODATA_DIR"
for name in geoip.dat geosite.dat; do
  target="$GEODATA_DIR/$name"
  staged="$GEODATA_DIR/.$name.new"
  if [ -L "$target" ] || { [ -e "$target" ] && [ ! -f "$target" ]; }; then
    printf 'Target is not a regular file; stop: %s\n' "$target" >&2
    exit 1
  fi
  if [ -e "$staged" ] || [ -L "$staged" ]; then
    printf 'Temporary path already exists; stop: %s\n' "$staged" >&2
    exit 1
  fi
done
verify_sha256 "$GEOIP_SOURCE" "$EXPECTED_GEOIP_SHA256"
verify_sha256 "$GEOSITE_SOURCE" "$EXPECTED_GEOSITE_SHA256"
BACKUP_DIR="/root/passwall-geodata-$(date +%Y%m%d-%H%M%S)"
mkdir -m 700 "$BACKUP_DIR"
[ ! -e "$GEODATA_DIR/geoip.dat" ] || cp -p "$GEODATA_DIR/geoip.dat" "$BACKUP_DIR/"
[ ! -e "$GEODATA_DIR/geosite.dat" ] || cp -p "$GEODATA_DIR/geosite.dat" "$BACKUP_DIR/"
install -m 0644 "$GEOIP_SOURCE" "$GEODATA_DIR/.geoip.dat.new"
install -m 0644 "$GEOSITE_SOURCE" "$GEODATA_DIR/.geosite.dat.new"
verify_sha256 "$GEODATA_DIR/.geoip.dat.new" "$EXPECTED_GEOIP_SHA256"
verify_sha256 "$GEODATA_DIR/.geosite.dat.new" "$EXPECTED_GEOSITE_SHA256"
mv -f "$GEODATA_DIR/.geoip.dat.new" "$GEODATA_DIR/geoip.dat"
mv -f "$GEODATA_DIR/.geosite.dat.new" "$GEODATA_DIR/geosite.dat"
Run only in a maintenance window after recording any original UCI value, with wired LAN management available and PassWall stopped orderly. Replace paths, active directory and checksums from a trusted release. The script rejects symbolic links, non-regular targets and pre-existing temporary paths. Confirm overlay space first; do not run until sources and hashes are verified.

Avoid concurrent Xray starts on low-memory devices

On a low-memory router, Xray run -test still creates a validation process. Running it while PassWall's main core is active can exhaust memory and trigger an OOM kill. Stop PassWall orderly through LuCI first, confirm no Xray core remains, then run the config test once. If it fails, keep the error and do not retry it concurrently or bulk-kill processes.

Use the command form below only when the device's Xray version supports it, the active config path is confirmed and no Xray process is running. After a successful test, start the service once through PassWall and observe the expected single core and logs. Do not manually launch a second Xray instance.

If the config test fails or startup remains unhealthy, first restore the recorded value of global_rules.geoip_url in the same PassWall setting, then restore the Geo files individually from the backup directory. Remove only a file added by this change when it did not exist before. Do not clear the entire Geo-data directory or restore unrelated router configuration.

Restore only the GeoIP and GeoSite files

sh
set -eu
GEODATA_DIR='REPLACE_WITH_DIRECTORY_FROM_ACTIVE_XRAY_CONFIG'
BACKUP_DIR='REPLACE_WITH_BACKUP_DIRECTORY_CREATED_ABOVE'
for name in geoip.dat geosite.dat; do
  if [ -e "$BACKUP_DIR/$name" ]; then cp -p "$BACKUP_DIR/$name" "$GEODATA_DIR/$name"; else rm -f "$GEODATA_DIR/$name"; fi
done
Use only when rollback is required and the PassWall core is stopped. Replace the directory and backup path recorded during installation. This handles only these two files; separately restore the recorded original global_rules.geoip_url in PassWall.

Verify the client and protocol scope

After repair, confirm that config testing passes, PassWall has only the expected core, listeners are correct and logs no longer report missing Geo data. From a wired LAN client, test one domestic direct TCP request and one overseas proxied TCP request. Confirm the routing result and target response separately; use an authorized target when checking egress.

The historical verification covered domestic direct TCP and overseas proxied TCP from a wired LAN client only. It does not establish wireless-client access, UDP forwarding or long-term stability. Before updating global_rules.geoip_url, confirm that the resource matches the current rule categories. If new GeoIP categories are added, select data that covers them and recheck storage. Keep network, DHCP, firewall, wireless and PassWall backups private because they may contain credentials.

Sources

Frequently Asked Questions

Does a missing Xray process mean the binary is gone?

Not necessarily. If logs and a config test point to missing Geo data, check the active config path, data files and referenced categories before changing the binary.

Can a reduced cn/private GeoIP file cover every rule?

No. It applies only when all referenced GeoIP categories are cn and private. Other categories require data that includes them.

Can I run Xray run-test while PassWall is active?

Avoid it on a low-memory router. Stop PassWall orderly, confirm no core is active, then run one config test to reduce OOM risk.