Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [Linux] Gateway install fails when XDG_RUNTIME_DIR is not set or systemd user session is unavailable [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#54415•Fetched 2026-04-08 01:27:52
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
4362228343622283
Participants
4362228343622283

Error Message

On Linux systems, openclaw gateway install fails with the error: 2. Provide clear error messages with remediation steps The installer fails with a cryptic error about the unit file not existing, when the real issue is the systemd user session being unavailable. 2. Improve error messages - Provide clear remediation steps

Root Cause

After debugging, I found:

  1. Missing XDG_RUNTIME_DIR: Without this, systemd cannot connect to the user session bus
  2. Linger not enabled: User services may not persist after logout
  3. No automatic remediation: The installer does not attempt to fix these common issues

Code Example

Gateway service install failed: systemctl enable failed: Failed to enable unit: Unit file openclaw-gateway.service does not exist.

---

export XDG_RUNTIME_DIR=/run/user/$(id -u)
mkdir -p "$XDG_RUNTIME_DIR"
loginctl enable-linger $(whoami)
openclaw gateway install --force
RAW_BUFFERClick to expand / collapse

Describe the bug

On Linux systems, openclaw gateway install fails with the error:

Gateway service install failed: systemctl enable failed: Failed to enable unit: Unit file openclaw-gateway.service does not exist.

The root cause is that the systemd user session is not available when XDG_RUNTIME_DIR is not set, which is common in:

  • SSH sessions without proper PAM configuration
  • Container environments
  • Minimal Linux installations

Steps to Reproduce

  1. On a fresh Linux installation or SSH session
  2. Ensure XDG_RUNTIME_DIR is not set: unset XDG_RUNTIME_DIR
  3. Run: openclaw gateway install
  4. Observe the failure

Expected Behavior

The installer should either:

  1. Automatically set up the required environment (XDG_RUNTIME_DIR, enable linger)
  2. Provide clear error messages with remediation steps

Actual Behavior

The installer fails with a cryptic error about the unit file not existing, when the real issue is the systemd user session being unavailable.

Root Cause Analysis

After debugging, I found:

  1. Missing XDG_RUNTIME_DIR: Without this, systemd cannot connect to the user session bus
  2. Linger not enabled: User services may not persist after logout
  3. No automatic remediation: The installer does not attempt to fix these common issues

Solution

Immediate Fix (for users)

export XDG_RUNTIME_DIR=/run/user/$(id -u)
mkdir -p "$XDG_RUNTIME_DIR"
loginctl enable-linger $(whoami)
openclaw gateway install --force

Recommended Code Changes

  1. Add pre-installation checks - Check XDG_RUNTIME_DIR and enable linger automatically
  2. Improve error messages - Provide clear remediation steps

Environment

  • OS: Linux (Ubuntu 22.04)
  • OpenClaw Version: 2026.3.23
  • Node.js: v24.14.1
  • systemd: systemd 249+

Additional Context

I have created a comprehensive diagnostic script that handles these cases and can auto-fix the issues. Happy to help test any fixes.

extent analysis

Fix Plan

To resolve the issue, follow these steps:

  • Set up the required environment:
    1. Set XDG_RUNTIME_DIR: export XDG_RUNTIME_DIR=/run/user/$(id -u)
    2. Create the directory: mkdir -p "$XDG_RUNTIME_DIR"
    3. Enable linger: loginctl enable-linger $(whoami)
  • Install the gateway:
    1. Run the installer with the --force flag: openclaw gateway install --force

Example code to automate the pre-installation checks and fixes:

# Pre-installation checks and fixes
if [ -z "$XDG_RUNTIME_DIR" ]; then
  export XDG_RUNTIME_DIR=/run/user/$(id -u)
  mkdir -p "$XDG_RUNTIME_DIR"
fi

if ! loginctl show-user $(whoami) | grep -q "Linger="; then
  loginctl enable-linger $(whoami)
fi

# Install the gateway
openclaw gateway install --force

Verification

To verify that the fix worked:

  1. Check the XDG_RUNTIME_DIR environment variable: echo $XDG_RUNTIME_DIR
  2. Verify that

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#installation#memory management#API rate limit#retriever error#indexing error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - 💡(How to fix) Fix [Linux] Gateway install fails when XDG_RUNTIME_DIR is not set or systemd user session is unavailable [1 participants]