LND MPP Errors — Fix Multi-Path Payment Failures

What Are MPP Errors?

Multi-Path Payments (MPP) split a single Lightning payment across multiple routes. When any sub-path fails, LND surfaces cryptic errors. This guide explains the most common LND MPP errors and how to fix them.

Error: insufficient_balance on MPP

LND splits payments based on available channel capacity. If individual channels are too small:

[ERR] HTLC attempt failed: insufficient_balance
code: TEMPORARY_CHANNEL_FAILURE

Fix: increase max_shard_size or top up outbound liquidity on larger channels.

Error: mpp_timeout

MPP requires all parts to arrive before a timeout (default 60s). Slow relay nodes cause partial delivery timeout:

[ERR] payment failed: mpp_timeout
htlc_hold_duration exceeded

Fix: reduce num_shards or increase payment_timeout_seconds in lnd.conf.

Error: max_parts exceeded

LND caps MPP shards at 16 by default. Large payments over fragmented channels hit this:

[ERR] payment failed: exceeded max_parts (16)

Fix: reduce sharding by consolidating channels or adjust max-cltv-expiry.

Error: no_route with MPP enabled

When MPP is on but the graph has no viable multi-path:

[ERR] unable to find route: no_route
no path found for amount 500000 msat

Fix: connect to better-connected peers, or disable MPP for that payment with --no_splitting.

Useful Debug Commands

# Check payment attempt shards
lncli trackpayment --payment_hash <hash>

# Force single-path payment
lncli sendpayment --dest <pubkey> --amt <sats> --no_splitting

# View channel balances for MPP planning
lncli listchannels | jq '.channels[] | {remote_pubkey, local_balance, remote_balance}'

Need more Lightning help? Visit clawguides.com (coming soon) or zap clawguides3@coinos.io