paperclipai/paperclip · error

Cannot verify or remove the background service: ${detection.

Error message

Cannot verify or remove the background service: ${detection.reason}. Retry when the service manager is available.

What it means

Thrown on Linux when systemd user-session support cannot be detected (detection.supported is false) yet a Paperclip systemd unit file is present at ~/.config/systemd/user/<service>. The uninstall command refuses to proceed because it cannot verify whether the service is loaded/active nor safely remove it without a working service manager. It tells the operator to retry once systemd --user is available.

Source

Thrown at cli/src/commands/uninstall.ts:60

  const instanceId = resolvePaperclipInstanceId();
  const detect = dependencies.detectServiceManager ?? detectServiceManager;
  const platform = dependencies.platform ?? process.platform;
  const userHomeDir = dependencies.userHomeDir ?? os.homedir();
  const detection = await detect({ instanceId, platform });
  const otherDefinitions = otherServiceDefinitions(platform, userHomeDir, instanceId);
  if (otherDefinitions.length > 0) {
    throw new Error(`Cannot remove the shared managed CLI while other instance services are installed: ${otherDefinitions.join(", ")}. Uninstall those services first.`);
  }
  if (!detection.supported && platform === "linux") {
    const definitionPath = path.join(
      userHomeDir,
      ".config",
      "systemd",
      "user",
      systemdServiceName(instanceId),
    );
    if (fs.existsSync(definitionPath)) {
      throw new Error(
        `Cannot verify or remove the background service: ${detection.reason}. Retry when the service manager is available.`,
      );
    }
  }
  if (detection.supported) {
    const status = await detection.manager.status();
    if (status.installed || status.active) await detection.manager.uninstall();
  }

  const paths = resolveInstallStorePaths();
  const hadStore = fs.existsSync(paths.cliRoot);
  if (hadStore) assertManagedInstallStore(paths);
  const shimRemoved = await withInstallStoreLock(async () => {
    if (hadStore) assertManagedInstallStore(paths);
    const removed = removeManagedShim(paths);

    const home = process.env.HOME;
    for (const rcFile of home ? [path.join(home, ".bashrc"), path.join(home, ".zshrc")] : []) {

View on GitHub (pinned to 67001ec6eb)

Solutions

1. Start or enable the systemd user session: `loginctl enable-linger $USER` and reconnect, or export XDG_RUNTIME_DIR=/run/user/$(id -u) before retrying.
2. Run uninstall from a session where `systemctl --user status` works (a graphical login or `machinectl shell` / proper PAM session).
3. Manually remove the unit file referenced by the error path, then re-run uninstall (it will skip the service block once the file is gone).

// Verify a working systemd user session before uninstall on Linux
import { execFileSync } from 'node:child_process';
function systemdUserAvailable(): boolean {
  if (process.platform !== 'linux') return true;
  try { execFileSync('systemctl', ['--user', 'is-active', 'default.target'], { stdio: 'ignore' }); return true; } catch { return false; }
}
// if (!systemdUserAvailable()) { prompt user to enable-linger / reconnect }

try {
  await uninstallCommand();
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Cannot verify or remove the background service')) {
    // detection.reason is embedded; either start systemd --user or rm the unit file then retry
    throw error; // surface to operator — recovery requires a session change
  } else throw error;
}

When it happens

Trigger: Running `paperclipai uninstall` on Linux inside an environment without a functioning systemd user session — e.g. an SSH session without systemd user instance, a container without systemd, or XDG_RUNTIME_DIR unset — while the unit file still exists from a prior install. detection.reason carries the specific cause (no systemd, no dbus, etc.).

Common situations: SSH login where `systemctl --user` fails (no user manager bus). Docker/container images lacking systemd. WSL1 or chroot environments. A unit file left behind after the session manager stopped working.

Related errors

• Cannot remove the shared managed CLI while other instance se
• ${manager.serviceName} is still loaded after uninstall.
• Systemd service values must not contain line breaks
• Refusing to write service definition through unsafe director
• Refusing to write service definition in directory not owned

AI-assisted analysis of paperclipai/paperclip@67001ec6eb (2026-08-12). Data as JSON: /api/errors/8e69a1c910461929. Report an issue: GitHub.