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

Xray Exits When macOS v2rayN Enables TUN: Check Geo File Paths

Follow the Geo file path branch only when Xray is the active core and its configuration check explicitly reports missing Geo files.

macOS v2rayN Xray TUN Geo files

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

  • If Xray exits and its local listener disappears after TUN is enabled while the physical network still works, check the core startup error before changing routes or DNS.
  • Confirm that Xray is active and run its read-only check against the configuration in use. Continue only when it explicitly reports a missing geoip.dat or geosite.dat path.
  • Preflight both source files and both target paths before copying. Stop if a target already exists, is a symbolic link, has uncertain content, or belongs to a different directory.
  • Darwin 26.2 on ARM64, v2rayN 7.23.2, and Xray 26.6.1 are the version reference for this guide. With Xray 26.6.2 or another combination, first identify the exact client and core versions. Use this branch only for an explicit missing Geo file path, then validate the configuration and make a real TUN request.

Confirm that the failure happens during core startup

If v2rayN starts on macOS but the Xray process and local listener disappear after TUN is enabled, first determine whether the core exited and what error appeared immediately before it stopped. A working physical network only shows that the ordinary network path is available; it does not prove that TUN, Xray, or the proxy node works, and it is not enough evidence to change DNS, MTU, or the route table.

A Geo file path mismatch applies to a narrow branch: the active core is Xray, and Xray's check of the configuration in use clearly says that geoip.dat or geosite.dat is missing from the location it searched. If the error concerns a port conflict, configuration syntax, permissions, a TUN device, or DNS, investigate that error separately. Do not copy Geo files as a guess.

Confirm the active core and check its configuration

Use the current v2rayN configuration and runtime state to identify the core; the mere presence of an Xray binary in an installation directory does not prove that it is active. Find the Xray executable and configuration path that the client actually starts, then run the validator for that core. Validation reads the configuration, so do not paste the configuration itself into a public discussion. Remove user names, private paths, and other local details from output before sharing it.

If the check explicitly reports a missing Geo data file, retain the file name and destination path from the error, then locate both source files. If the same missing-file error cannot be reproduced, stop before copying anything and avoid masking a different startup problem with a file change.

Inspect the active Xray binary and validate its configuration

shell
XRAY_BIN='/path/to/current/xray'
CONFIG_FILE='/path/to/current/config.json'
"$XRAY_BIN" version
"$XRAY_BIN" run -test -config "$CONFIG_FILE"
Replace these paths with the Xray binary and configuration the client currently starts. The check reads the configuration; its output may contain local paths, so sanitize it before sharing.

Compare the Geo source files with Xray's asset directory

Xray must find the Geo data files at the locations referenced by its configuration. The files may exist in one program directory while the core searches another. That directory difference matters only when both the validator error and the file locations agree. Determine the target from Xray's launch arguments, validation output, or the active core directory. Do not reuse a path from a different macOS release, an old installation, or a different core.

The read-only check below lists the two files in the source and target directories. Full paths may reveal a local user name or app location, so redact them before publishing. If a source file is missing, a target file already exists, a target is a link, or the source does not match the active core, stop and preserve the existing files.

Compare Geo files in both directories without changing them

shell
SOURCE_DIR='/path/to/source-directory'
TARGET_DIR='/path/to/xray-asset-directory'
for name in geoip.dat geosite.dat; do
  for dir in "$SOURCE_DIR" "$TARGET_DIR"; do
    if [ -e "$dir/$name" ] || [ -L "$dir/$name" ]; then
      ls -ld "$dir/$name"
    else
      printf 'MISSING: %s/%s\n' "$dir" "$name"
    fi
  done
done
Replace both directories with the actual paths to inspect file metadata only. The output may disclose local directory names; do not post it without redaction.

Copy only after both files and target paths pass preflight

Copy files only when the active core is confirmed as Xray, its check explicitly reports that at least one of these files is missing from the target, both source files exist and are not symbolic links, the target directory already exists, and neither target name is occupied. The script below checks both sources and both destinations before copying either file. It will not overwrite a destination or create a directory.

If the command stops because of a permission or filesystem error, do not run it again immediately or apply a recursive permission change. Repeat the read-only directory check first to see which targets were added. Stop and preserve the current state if a target already existed, its contents are from an unknown version, the validation path does not match, or the active core is not Xray.

Preflight both files before copying missing Geo data

shell
set -eu
SOURCE_DIR='/path/to/source-directory'
TARGET_DIR='/path/to/xray-asset-directory'
test -d "$SOURCE_DIR" && test -d "$TARGET_DIR"
for name in geoip.dat geosite.dat; do
  src="$SOURCE_DIR/$name"
  dst="$TARGET_DIR/$name"
  test -f "$src" && test ! -L "$src" || { printf 'Invalid source: %s\n' "$src"; exit 1; }
  if [ -e "$dst" ] || [ -L "$dst" ]; then
    printf 'Target already exists; stop: %s\n' "$dst"
    exit 1
  fi
done
for name in geoip.dat geosite.dat; do
  cp -n "$SOURCE_DIR/$name" "$TARGET_DIR/$name"
done
Run only after every condition above is met and the directories have been replaced. This adds files; if the command fails partway through, inspect what was copied before retrying.

Restart and check that the same error is gone

After copying, run the validator again with the same Xray binary and configuration. Restart v2rayN and enable TUN only if the check no longer reports the Geo path error. Then confirm that the Xray process and local listener remain present and load an HTTPS page through actual TUN traffic. A successful configuration check or a lit TUN switch alone does not prove that real traffic has recovered.

If the core still exits, capture the new specific error and stop changing Geo paths. If Xray remains running but real access fails, continue with the route, DNS, or upstream connection for that request; the file check does not prove those paths are healthy.

Version scope, rollback, and unknowns

Use this procedure only when the active Xray explicitly reports a missing Geo file path. Darwin 26.2 on ARM64, v2rayN 7.23.2, and Xray 26.6.1 are the version reference here, not a compatibility guarantee for other combinations. With Xray 26.6.2 or another version, record the exact client and core versions, validate the configuration using a method supported by that version, and verify core startup and a real TUN request. Do not claim compatibility or recovery before those checks pass. Upstream issue #9715 describes a path difference reported with v2rayN 7.23.3 on Arch Linux. It is not a formal macOS repair announcement and does not establish that the current Darwin environment is fixed.

To roll back, stop v2rayN and Xray, then remove only the files confirmed to have been newly added by this operation and absent beforehand. Keep the original Geo files. Do not delete the whole core directory or replace files with a guessed older version. If you cannot tell whether a file was created by this change, preserve it and pause cleanup.

Sources

Frequently Asked Questions

Can I copy Geo files as soon as Xray disappears after TUN starts?

No. Confirm that Xray is the active core and that its current configuration check explicitly reports a missing Geo file path. Other startup errors do not match this procedure.

Does a working physical network prove that DNS and routes are fine?

No. Direct access only shows that the ordinary physical network path works; it does not establish that TUN or DNS and routing inside TUN are working.

Should I replace geoip.dat if a file already exists in the target directory?

Do not overwrite it. Confirm which version it came from and which path the validator actually searches. Stop if the file's contents or source are unclear.

Does a passing configuration check mean the proxy is restored?

No. Restart the core, confirm that its listener remains available, and make a real HTTPS request through TUN.