zeroclaw-labs/zeroclaw · warning · DiagItem

systemd user lingering disabled; user service may stop after

Error message

systemd user lingering disabled; user service may stop after logout. Enable with: loginctl enable-linger {$user}

What it means

A `zeroclaw doctor` warning from `systemd_linger_diag_item` (via `check_environment`, only when a systemd user runtime is present): systemd user lingering is disabled for the current user. Without lingering, the user manager (and the zeroclaw user service inside it) is stopped at logout, so an unattended daemon dies with your session. The localized message includes the exact fix: `loginctl enable-linger <user>`.

Source

Thrown at crates/zeroclaw-runtime/src/doctor/mod.rs:1761

    // Optional tools
    check_command_available("curl", &["--version"], cat, items);

    if crate::service::linux_systemd_runtime_present() {
        items.push(systemd_linger_diag_item(
            crate::service::systemd_user_linger_status(),
        ));
    }
}

fn systemd_linger_diag_item(status: crate::service::SystemdUserLinger) -> DiagItem {
    let cat = "environment";
    match status {
        crate::service::SystemdUserLinger::Enabled => DiagItem::ok(
            cat,
            crate::i18n::get_required_cli_string("cli-doctor-systemd-linger-enabled"),
        ),
        crate::service::SystemdUserLinger::Disabled { user } => DiagItem::warn(
            cat,
            crate::i18n::get_required_cli_string_with_args(
                "cli-doctor-systemd-linger-disabled",
                &[("user", user.as_str())],
            ),
        ),
        crate::service::SystemdUserLinger::Unknown => DiagItem::warn(
            cat,
            crate::i18n::get_required_cli_string("cli-doctor-systemd-linger-unknown"),
        ),
    }
}

fn check_cli_tools(items: &mut Vec<DiagItem>) {
    let cat = "cli-tools";

    let discovered = crate::tools::discover_cli_tools(&[], &[]);

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Run `loginctl enable-linger <user>` (the message names your user) so the user manager survives logout.
2. Restart the zeroclaw user service afterwards and log out/in to verify it stays up.
3. Re-run `zeroclaw doctor` and confirm the linger item reports enabled (ok).

Example fix

# before: doctor warns lingering disabled for user alice

# after
loginctl enable-linger alice
systemctl --user restart zeroclaw

match zeroclaw_runtime::service::systemd_user_linger_status() {
    zeroclaw_runtime::service::SystemdUserLinger::Disabled { user } => {
        eprintln!("run: loginctl enable-linger {user}");
    }
    _ => {}
}

When it happens

Trigger: Running `zeroclaw doctor` on a Linux host with systemd where `loginctl show-user <user>` reports lingering disabled — the common state after installing zeroclaw as a user service for the first time.

Common situations: Daemon installed via `zeroclaw service install` on a fresh machine; SSH-based setups where the admin logs out expecting the bot to keep running; shared servers where linger was never enabled.

Related errors

• neither $SHELL nor %ComSpec% is set
• systemd user lingering could not be checked with loginctl
• systemctl restart failed: {}
• Linux service {action} only manages the default zeroclaw ser
• {cmd} found but returned non-zero

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/18fb87b47ba872d6. Report an issue: GitHub.