LIGHTNING-AUTOCLEAN-ONCE(7)

💅 LIGHTNING-AUTOCLEAN-ONCE(7) — the autoclean-once page, bestie edition

okay so this is the manual page for autoclean-once, from LIGHTNING-AUTOCLEAN-ONCE(7). yes that's the whole title, she's long, she's iconic, we move 🎀

---

✨ NAME ✨

autoclean-once — a single deletion of old invoices/payments/forwards. one sweep. that's it. that's the vibe 🧹

---

🌸 SYNOPSIS 🌸

autoclean-once subsystem age

---

🦋 DESCRIPTION 🦋

The autoclean-once RPC command tells the autoclean plugin to do a single sweep to delete old entries. It's basically the manual version (or the bonus round, your call) of all those autoclean-...-age parameters that make autoclean run once per hour — go peek at lightningd-config(5) for those, iykyk.

• subsystem (string) (one of "succeededforwards", "failedforwards", "succeededpays", "failedpays", "paidinvoices", "expiredinvoices", "networkevents") — which subsystem to clean, bestie. currently supported subsystems are:
  • failedforwards — routed payments which did not succeed (failed or local_failed in listforwards status).
  • succeededforwards — routed payments which succeeded (settled in listforwards status).
  • failedpays — payment attempts which did not succeed (failed in listpays status).
  • succeededpays — payment attempts which succeeded (complete in listpays status).
  • expiredinvoices — invoices which were not paid (and cannot be) (expired in listinvoices status).
  • paidinvoices — invoices which were paid (paid in listinvoices `status).
  • networkevents — all events in listnetworkevents (added v25.12)

NOTE: until v25.12, the uncleaned field contained all entries not removed (e.g. in failedforwards it counted all forwards, not just failed ones). This was an interface only an engineer could love, so it was fixed. 🛠️

• age (u64) — non-zero number in seconds. how many seconds old an entry must be to get deleted. literally the "you must be this old to ride" sign 🎢

---

👑 RETURN VALUE 👑

On success, an object containing autoclean is returned. It's an object containing:

• succeededforwards (object, optional):
  • cleaned (u64) — the number of successful forwards deleted.
  • uncleaned (u64) — the number of successful forwards not deleted (too new).
• failedforwards (object, optional):
  • cleaned (u64) — the number of failed forwards deleted.
  • uncleaned (u64) — the number of failed forwards not deleted (too new).
• succeededpays (object, optional):
  • cleaned (u64) — the number of successful payments deleted.
  • uncleaned (u64) — the number of successful forwards not deleted (too new).
• failedpays (object, optional):
  • cleaned (u64) — the number of unsuccessful payments deleted.
  • uncleaned (u64) — the number of unsuccessful payments not deleted (too new).
• paidinvoices (object, optional):
  • cleaned (u64) — the number of paid invoices deleted.
  • uncleaned (u64) — the number of paid invoices not deleted (too new).
• expiredinvoices (object, optional):
  • cleaned (u64) — the number of expired invoices deleted.
  • uncleaned (u64) — the number of expired invoices not deleted (too new).
• networkevents (object, optional) (added v25.12):
  • cleaned (u64) — total number of deletions done this run. (added v25.12)
  • uncleaned (u64) — the total number of entries not deleted this run. (added v25.12)

---

💖 AUTHOR 💖

Rusty Russell rusty@rustcorp.com.au is mainly responsible. yes, the Rusty. we stan 🫶

---

🌈 SEE ALSO 🌈

lightningd-config(5), lightning-autoclean-status(7)

---

⭐ RESOURCES ⭐

Main web site: https://github.com/ElementsProject/lightning

---

🔥 EXAMPLES 🔥

Example 1:

Request:

$ lightning-cli autoclean-once "failedpays" "1"

{
  "id": "example:autoclean-once#1",
  "method": "autoclean-once",
  "params": [
    "failedpays",
    1
  ]
}

Response:

{
  "autoclean": {
    "failedpays": {
      "cleaned": 0,
      "uncleaned": 7
    }
  }
}

Example 2:

Request:

$ lightning-cli autoclean-once "succeededpays" "1"

{
  "id": "example:autoclean-once#2",
  "method": "autoclean-once",
  "params": [
    "succeededpays",
    1
  ]
}

Response:

{
  "autoclean": {
    "succeededpays": {
      "cleaned": 7,
      "uncleaned": 0
    }
  }
}

---

and that's the whole page, bestie 💜 this iconic little number ships with Core Lightning v26.06.9 — go forth and clean, mwah 🎀✨