Use Xray server logs to identify which stage failed, not to collect every connection. Confirm the running configuration, capture one authorized failure in a short time window, then restore the normal logging policy and retain only the evidence you need.

Key Takeaways

The service owner and active configuration determine where logs go.

Startup, authentication and outbound failures require different evidence.

A port conflict calls for ownership checks, not blind process termination.

Redact copies; preserve protected originals only within an agreed retention period.

Temporary debug logging ends with verified restoration, not merely an edited file.

What can Xray server logs establish?

The breakdown of self-hosting ownership explains why the operator owns both troubleshooting and privacy. This procedure targets an already authorized Xray-core v26.3.27 instance on Ubuntu 24.04 LTS, with systemd 255 as the journal reference. Confirm installed versions and the actual supervisor before using commands. Container or panel-managed instances need their own log owner; do not assume xray.service exists.

The author did not perform a complete end-to-end deployment experiment. Commands below describe reader checks, and no displayed failure or success is a measured result. They do not require changing your everyday proxy, VPN or other network client. Use an independent authorized client for the reproduction.

A log message is evidence of what a component recorded, not proof of everything that happened. Silence can mean the event was filtered, went elsewhere, or never reached Xray. Likewise, a TLS connection can reach a fallback site without successful proxy authentication. For that distinction, use the paired Trojan certificate and verification procedure.

Step 1: Identify the running instance and log destination

Start with the service owner, executable, version and configuration path. On a systemd installation, choose the exact unit after inspecting the inventory. The following commands inspect the example unit; replace it if the authorized instance has another name. Review output locally because service arguments and environment can contain secrets.

XRAY_UNIT='xray.service'
systemctl show "$XRAY_UNIT" -p FragmentPath -p ExecStart -p User -p Group -p MainPID
systemctl cat "$XRAY_UNIT"
xray version

Resolve the actual executable from ExecStart; the xray on your shell path may not be the service binary. Inspect the referenced configuration and any directory arguments locally. Do not paste unit contents, environment files or complete configuration into a ticket. If ownership is ambiguous, stop before enabling debug or restarting anything.

Xray supports access and error destinations and a loglevel. Its rolling documentation explains their meaning; the pinned tag's parser confirms the fields used here.［1］［2］ This is a log fragment to merge into an existing reviewed configuration, not a complete server configuration:

{
  "log": {
    "access": "none",
    "error": "",
    "loglevel": "warning",
    "dnsLog": false
  }
}

Here the error destination is console output, which reaches the journal only when the unit actually captures it. An explicit Xray error log file path uses another destination. Access logging disabled does not mean no personal information can appear in error output. Establish the real destination before concluding that the journal is empty or the process has no logs.

Step 2: Capture one bounded failure

Agree on a short reproduction window, one client, one intended destination and a maximum collection size. Record UTC times and a local case label that contains no user identity. Use a working private directory with restrictive permissions and enough space. The sample limits journal selection to 300 entries within explicit times; choose tighter limits if entries are unusually large.

Replace both time placeholders before execution. The selected interval must bracket your single authorized reproduction, not a full day of unrelated sessions. journalctl provides unit and time filters in the Ubuntu reference.［3］

START_UTC='YYYY-MM-DD HH:MM:SS UTC'
END_UTC='YYYY-MM-DD HH:MM:SS UTC'
umask 077
journalctl --unit "$XRAY_UNIT" --since "$START_UTC" --until "$END_UTC" \
  --no-pager --output short-iso --lines 300 > xray-case.private.log

Do not overwrite an existing evidence file; choose an unused private case directory first. Verify the selected unit, time range, file permissions and size locally. If the failure is missing, extend only the necessary boundary after checking the log destination. Do not enable payload capture, dump subscriptions or repeatedly reproduce traffic until the file fills a disk.

If warning-level output is insufficient, privately back up the exact active configuration and its permissions. For an approved maintenance window, temporarily change only this instance to a supported diagnostic level, validate with its actual binary and configuration path, then use its owning supervisor to apply the change. Record the previous level and a firm end time. A syntax check does not prove a restart will succeed; retain the independent management connection.

Step 3: Separate startup, authentication and outbound faults

Read the event sequence rather than searching for one magic error string. A startup failure precedes client acceptance; authentication requires an appropriate inbound connection; outbound errors occur after a request has reached a stage capable of attempting its destination. Do not infer a missing stage from an unrelated message at a similar time.

Layer	What to establish	Next bounded check
Startup	Correct binary, configuration loaded, intended listener present	Inspect service exit and the first relevant error
Listener conflict	Exact address, transport, port and owning process	Match listener PID to its supervisor before any action
TLS or inbound authentication	Client endpoint, identity and protocol match	One correct and one deliberately invalid disposable credential
Outbound	Accepted request targets the authorized destination	Check that destination's route and name-resolution configuration
Missing evidence	Selected source and time window cover the attempt	Correct selection before raising verbosity

For address already in use, inspect both TCP and UDP listeners locally. A port number alone is not enough: address family and bind address matter. Link the reported PID to its executable, service unit, container or panel owner. These are inspection commands, not a termination recipe:

sudo ss -lntup
systemctl status "$XRAY_UNIT" --no-pager

An expected owner may be another legitimate instance or website. Do not kill it, overwrite its port, or restart the whole host. Stop and arrange an unused listener or an explicitly approved migration with the owner. If the PID cannot be attributed, leave it intact.

For authentication failures, use disposable test identity and revoke it afterward. Never ask someone to share their real subscription, password or private key. The subscription-link secrecy guide explains why encoded links remain credentials. For a client-side REALITY mismatch, follow VLESS/REALITY connection troubleshooting after establishing the server-side stage; do not replace that evidence with speculative server tuning.

Step 4: Redact a copy while preserving diagnostic context

Keep the original only in a restricted location with a named owner and deletion deadline. Make a separate sharing copy. Replace credentials, subscription URLs, UUIDs, email labels, private keys and account identifiers. Also review client IPs, destination hostnames, query strings and file paths for personal or internal information.

Use consistent labels such as CLIENT_A, INBOUND_A and DESTINATION_A so relationships survive redaction. Preserve timestamps, relative ordering, severity, stage and relevant error class. If an exact hostname is needed to diagnose a certificate mismatch, share it only with the authorized recipient through the approved private channel.

Do not trust a regex to catch all secrets. Inspect each line and the surrounding context, especially multiline errors and copied command output. Remove payloads entirely rather than masking fragments of a conversation. Address masking in an implementation is useful but not a substitute for reviewing identities, URLs and application data in the final sharing copy.

Step 5: Bound permissions, disk use and retention

Give only the service identity the write access required for its chosen destination, and only authorized operators access to evidence. Do not use world-writable permissions to make logging work. Configuration secrets, logs and redacted exports have different audiences and should not share a publicly served directory.

For a file destination, document maximum size, retention and the implementation's supported reopen behavior before choosing rotation. A renamed file can leave a running process writing to the old descriptor. Verify the next authorized event reaches the intended active file; do not prescribe a guessed signal or generic copytruncate policy as universally safe Xray log rotation.

The journal has service-managed storage limits, including SystemMaxUse and RuntimeMaxUse; those are journal storage policies, not per-Xray budgets.［4］ On a shared host, do not change global limits or run journal vacuum to solve one instance's problem. Ask the storage owner for an approved policy or isolate this instance's log destination.

If the disk is full, first preserve a small relevant sample on an approved location with space, note timestamps and disk/inode usage, and stop the owned source of excessive output through its supervisor if authorized. Then remove only expired files demonstrably owned by this instance under its retention policy. Never delete other services' logs or the entire journal. If evidence cannot be safely preserved or ownership is unclear, stop and escalate to the responsible operator.

Step 6: Restore logging and verify the lifecycle

Restore the exact prior logging level and temporary destination settings, validate the final configuration, and apply it through the instance owner. Recheck the running version, service state, listener and independent management path. Generate one permitted ordinary event to confirm logging still works without the temporary diagnostic detail. Merely restoring a file does not establish what the live process loaded.

Check the agreed size cap, retention mechanism and actual permissions. For file rotation, verify new output reaches the active destination and stale owned files age out as intended. Revoke disposable credentials and delete private and sharing copies at their deadlines. If a restart fails, restore the previous compatible binary/configuration pair and verify the original service before any further reproduction.

Repeated diagnostic sessions are an operational cost. At the decision about who stores logs and maintains the server, compare VPS operation with a managed VPN service. That choice does not transfer a managed service's privacy claims to your self-hosted instance or guarantee that changing service will repair this fault.

Summary

Attribute the active binary, configuration, supervisor and destination first.
Collect one failure with explicit time and size boundaries.
Separate listener, authentication and outbound evidence before changing settings.
Share a manually reviewed redacted copy and limit original retention.
Restore the live logging policy, revoke test identity and verify original service health.

FAQ

Why are my Xray server logs empty?

The event may be filtered, stored in a file, sent to a container runtime, or absent because traffic never reached Xray. Confirm the active instance, destination and interval before increasing verbosity. Silence does not prove successful authentication or no user activity.

Should I leave debug enabled permanently?

No default recommendation here requires that. Use the least detail sufficient for the incident, a stated end time and an agreed retention budget. After the reproduction, restore the previous policy and verify the running process loaded it.

Can I share a subscription link after hiding its prefix?

No. Encoded content and query parameters can still carry credentials. Replace the entire secret in a sharing copy, use consistent harmless labels, and revoke it if disclosed. Keep real authentication material out of tickets and public chats.

Can I kill the process holding Xray's port?

Not without identifying its owner and obtaining authorization. Check the exact listener address, TCP or UDP, PID and supervisor. A legitimate website or another instance may own it; choose an unused port or arrange a controlled migration instead.

Does a successful TLS connection prove proxy login?

No. TLS may reach a fallback website or fail at a later authentication stage. Use an explicitly configured test client, an authorized destination and a deliberately wrong disposable credential; compare proxy outcomes rather than website availability alone.

Is journal vacuum safe for one noisy service?

It can remove journal data belonging to other services, so it is not the scoped cleanup prescribed here. Preserve a small relevant sample first, control only your instance's output and follow its owned-file retention policy with the storage administrator.

What closes a troubleshooting session?

The live process has its prior logging policy, ordinary logging still works, original services and management remain healthy, test credentials are revoked, and evidence has an owner and deletion deadline. An edited configuration or a completed capture alone is insufficient.

Disclaimer: This procedure is based on the listed official documentation and pinned implementation, not a report of author-run failures or successes. Inspect only authorized instances and traffic, comply with law and provider terms, and stop if ownership, storage safety or recovery cannot be established.

Sources:

Log Configuration https://xtls.github.io/en/config/log.html
Xray-core v26.3.27 log configuration implementation https://github.com/XTLS/Xray-core/blob/v26.3.27/infra/conf/log.go
journalctl — systemd 255 on Ubuntu 24.04 LTS https://manpages.ubuntu.com/manpages/noble/man1/journalctl.1.html
journald.conf — systemd journal service configuration https://github.com/systemd/systemd/blob/v255/man/journald.conf.xml

Sources checked 11 October 2026.

Read Xray Server Logs Without Exposing Credentials