"Payment timed out": what Lightning timeouts and stuck payments really mean
Last updated:
A Lightning payment that "timed out" can mean two very different things, and mixing them up is how people end up paying twice. LND reports FAILURE_REASON_TIMEOUT ("payment attempts exceeded timeout"). Core Lightning stops retrying when its retry_for window runs out. Wallets usually show "payment timed out" or leave the payment marked as pending.
The key question is whether any part of the payment is still in flight. A timeout that ended cleanly with nothing pending is just a failed payment. A payment whose HTLC is still locked somewhere along the route has not failed yet, even if the app says it timed out.
Live Lightning routing signal
This is a historical ranking proxy built from observed route candidates over the last 24 hours. It is not a payment success probability and does not measure directional liquidity for your specific path.
Check current routing reliability on the dashboard →Two kinds of timeout
1. Pathfinding ran out of time
When you pay, your node tries a route, learns from any failure, and tries again. It keeps going until it succeeds, runs out of candidate routes, or hits a time limit. LND's lncli payinvoice defaults to a 60-second --timeout, and applications using the router API set timeout_seconds themselves. If the limit arrives first, the node stops launching new attempts and reports a timeout. If no attempt is still pending, the payment has definitively failed, nothing was spent, and you can retry.
2. An HTLC is stuck in flight
Each attempt locks funds in an HTLC at every hop. Usually it settles or fails within seconds. But if a node on the path goes offline, or a recipient deliberately holds the payment (for example with a hold invoice), the HTLC stays locked until it settles or its time-lock (CLTV) expires. That can take minutes to hours, and in rare cases longer. During that window the payment is neither complete nor failed. Your node shows it as in flight or pending even after the app has given up waiting.
Common causes
- Many failed attempts. Liquidity-starved routes generate attempt after attempt until the timer runs out. See insufficient liquidity.
- Slow or offline hops. A forwarding node with poor uptime or heavy load can hold HTLCs longer than expected.
- Network latency, especially nodes and wallets running over Tor, where each attempt takes longer and fewer fit inside the timeout.
- Mobile wallets losing connection or being suspended by the operating system mid-payment.
- Recipient-side holds, such as hold invoices or a recipient node that is slow to settle.
- A timeout set too short by an application for the size or difficulty of the payment.
What senders should do
- Check the payment status before retrying. In LND, use
lncli trackpayment <payment_hash>orlistpayments. In Core Lightning, uselistpaysorlistsendpays. Look for any attempt still marked in flight or pending. - If nothing is in flight, the payment failed. Retry the same invoice if it has not expired, ideally after a short wait.
- If something is in flight, wait. Do not ask the recipient for a new invoice and pay that too. If the original HTLC later settles, you will have paid twice. Paying the same invoice again is generally protected by the shared payment hash, and most node software refuses to start a second payment for a hash that is still pending.
- Keep your node or wallet online until the payment resolves, so it can process the settlement or failure.
What developers and node operators can do
- Tune timeouts to the use case. Point-of-sale flows need short timeouts with clear user messaging. Large or difficult payments benefit from longer ones.
- Make "pending" a first-class state in your UI and backend. Never treat an in-flight payment as failed, and never auto-generate a replacement invoice while one is pending.
- Use idempotent payment records keyed by payment hash, so retries cannot double-charge.
- Peer with nodes that have strong uptime. Many stuck HTLCs trace back to a single unreliable hop.
- Monitor pending HTLCs and alert when the count or age climbs.
- Record attempts, latency, and failure codes for every terminal outcome. Optaimaze's developer API and telemetry guide describes one privacy-preserving way to submit outcome data without sending invoices or payment hashes.
Timeouts and route stability
Timeouts tend to cluster when routing conditions are unstable and the best candidates keep changing. The Optaimaze insights dashboard tracks leadership changes and volatility among observed route candidates over time. It is a historical ranking signal that can add context when you investigate a spike in timeouts, not a prediction for any single payment.
Lightning payment error guides
Payment timeout FAQ
What does "payment timed out" mean on Lightning?
Usually it means your node stopped trying new routes because a time limit was reached. If no attempt is still in flight, the payment failed and nothing was spent. If an HTLC is still pending somewhere on the route, the payment is unresolved and could still succeed or fail.
Is it safe to retry a timed-out Lightning payment?
Check the payment status first. If nothing is in flight, retrying the same invoice is fine. If an attempt is still pending, wait. Never pay a new invoice for the same purchase while the first payment is in flight, or you may pay twice.
How long can a Lightning payment stay pending?
Most payments resolve in seconds. A stuck HTLC stays locked until it settles or its time-lock expires, which can take minutes to hours and in rare cases longer, depending on the CLTV deltas along the route.
Why do Lightning payments time out more often over Tor or on mobile?
Each payment attempt involves several network round trips. Tor latency and unstable mobile connections slow every attempt, so fewer attempts fit inside the timeout, and a suspended app may stop processing updates.
How can developers reduce Lightning payment timeouts?
Set timeouts that fit the use case, treat pending as a distinct state, key payment records by payment hash to avoid double charges, peer with high-uptime nodes, and monitor pending HTLC counts and ages.
Check current routing reliability.
See current top-ranked route candidates, leadership changes, volatility, and risk level from recent snapshots.