Maximum HTLC value in flight

The cap is a single field, max_htlc_value_in_flight_msat, agreed when a channel opens and enforced on every payment afterwards. Eclair ships a default of 5,000,000,000 millisatoshi or 45 percent of channel capacity, whichever is smaller, so a 60 mBTC channel gets 27 mBTC. Your large Lightning payment can fail on a channel that visibly holds enough money, and this is often the reason.

How it works

Maximum HTLC value in flight is negotiated, not imposed: each side declares the ceiling it wants the other to respect.

The field travels in open_channel (message type 32) and returns in accept_channel (type 33); dual funded channels carry it in open_channel2 (64) and accept_channel2 (65). BOLT 2 describes it as "a cap on total value of outstanding HTLCs offered by the remote node, which allows the local node to limit its exposure to HTLCs". Note the direction: the number you send restrains your peer, not you, so a channel carries two caps that need not match.

Enforcement is blunt at both ends. A sending node must not add a payment if the total value it already has offered would then pass the remote's cap, and a receiver whose peer breaks the rule is told to warn and drop the connection, or fail the channel outright. Its sibling max_accepted_htlcs counts pending payments instead of measuring them, and the specification hard-caps that one at 483, falling to 114 when the channel uses zero fee commitments. The value cap has no equivalent ceiling: it is pure node policy, the spec's only guard being that a receiver may refuse a channel whose figure looks too small.

Money sitting still is untouched. A channel can hold many times the cap in settled balance, because the limit counts only payments in motion, the ones that would need untangling on chain if the channel closed badly.

Where you see it

Maximum HTLC value in flight never appears in the public Lightning graph, so no channel explorer will show it to you.

It leaks in one specific way. BOLT 7 requires a node publishing a channel_update to set htlc_maximum_msat, the largest single payment it will forward, to no more than the max_htlc_value_in_flight_msat it received from its peer. A private number therefore puts a hard roof on a public one: a cautious peer forces the advertised figure down, though a node is free to advertise less than its peer allows.

Defaults differ enough between implementations to matter. Eclair's reference configuration sets max-htlc-value-in-flight-msat to 5,000,000,000 and max-htlc-value-in-flight-percent to 45, applies whichever is smaller, and notes the setting is per direction, so both together can reach twice the figure. Eclair also sets max-accepted-htlcs to 30, while the LND sample configuration ships default-remote-max-htlcs at 483, the specification maximum. Two operators running untouched defaults can disagree by a factor of sixteen on the count alone.

For a buyer the symptom is a payment that fails without explanation. Splitting the amount into parts does not rescue it when the parts take the same channel, because the cap adds them together. ACINQ, which publishes those eclair defaults, also ships Phoenix, the phone wallet reviewed here; any wallet opening channels for you picks these numbers on your behalf.

Maximum HTLC value in flight vs channel capacity

Channel capacity is the amount locked in a channel's funding output, while maximum HTLC value in flight governs how much of that amount may be mid-payment at any one moment.

Capacity is a public fact, fixed by the funding transaction and announced to the whole network. The in-flight cap is private, exchanged only between the two peers, set separately for each direction, and chosen by policy rather than arithmetic. Eclair's percentage default makes the gap concrete: the 45 percent applies to each direction on its own, so more than half the capacity is barred from moving one way at a time. A channel that shows plenty of room on your side can still turn a payment down, and the figure that refused it is one you cannot look up.