Generic error message for Lightning payment failures hides actual cause

[piotr-iohk]

What happened?

When sending Lightning payments to Phoenix wallet, payments failed with the generic error "Your instant payment failed, please try again". The actual causes varied by payment size but were never surfaced to the user.

Observed behavior:

• Attempted multiple payments to Phoenix wallet (111 sats, 1k, 10k, 15k sats)
• All failed with generic error: "Your instant payment failed, please try again"
• Eventually succeeded with a 5k sat payment
• Error message gave no indication of the actual failure reason

Expected behavior:
The error message should:

1. Distinguish between routing failures vs recipient rejections
2. Indicate when retries might help vs when the payment amount is the issue
3. Provide actionable guidance based on the specific failure type

Root Cause Analysis (from logs)

Two distinct failure modes were observed:

Failure Mode 1: Small payments (111-1000 sats) - Phoenix JIT rejection

• Phoenix wallet rejected with TemporaryNodeFailure(0x2002)
• LDK marked route hint as failed, couldn't find alternative route
• Final error: ROUTE_NOT_FOUND

09:35:04 - Initiated sending 111000 msat
Onion Error[from 02bd5206...: TemporaryNodeFailure(0x2002)]
PaymentFailed { reason: Some(RouteNotFound) }

09:35:23 - Initiated sending 1000000 msat
Onion Error[from 02bd5206...: TemporaryNodeFailure(0x2002)]
PaymentFailed { reason: Some(RouteNotFound) }

Failure Mode 2: Large payments (10k-15k sats) - Routing liquidity issues

• Various intermediate routing nodes rejected with TemporaryChannelFailure(0x1007)
• LDK exhausted all retry attempts across multiple routes
• Final error: RETRIES_EXHAUSTED

09:59:24 - Initiated sending 10000000 msat
Onion Error[from 027e9dd6...: TemporaryChannelFailure(0x1007)]
Onion Error[from 02baa725...: TemporaryChannelFailure(0x1007)]
Onion Error[from 028d1db1...: TemporaryChannelFailure(0x1007)]
Onion Error[from 030ef510...: TemporaryChannelFailure(0x1007)]
PaymentFailed { reason: Some(RetriesExhausted) }

10:02:38 - Initiated sending 15000000 msat
Onion Error[from 02dd3fcd...: TemporaryChannelFailure(0x1007)]
PaymentFailed { reason: Some(RetriesExhausted) }

Successful payment: 5k sats

10:18:49 - Initiated sending 5000000 msat
PaymentSent { amount_msat: Some(5000000), fee_paid_msat: Some(7856) }

Note: This was NOT an insufficient local funds issue. The channel had ~49k sats available.

Full Payment Timeline

Time	Amount	Error	Result
09:35:04	111 sats	TemporaryNodeFailure(0x2002)	RouteNotFound
09:35:23	1,000 sats	TemporaryNodeFailure(0x2002)	RouteNotFound
09:56:01	1,000 sats	TemporaryNodeFailure(0x2002)	RouteNotFound
09:59:24	10,000 sats	TemporaryChannelFailure(0x1007) x4	RetriesExhausted
10:00:14	10,000 sats	TemporaryChannelFailure(0x1007)	RetriesExhausted
10:02:38	15,000 sats	TemporaryChannelFailure(0x1007)	RetriesExhausted
10:05:59	10,000 sats	TemporaryChannelFailure(0x1007)	RetriesExhausted
10:12:28	10,000 sats	TemporaryChannelFailure(0x1007)	RetriesExhausted
10:18:49	5,000 sats	-	SUCCESS

Steps to Reproduce

1. Open Bitkit with an active Lightning channel (~50k sats balance)
2. Generate invoice in Phoenix wallet for various amounts
3. Attempt payments of 10k-15k sats
4. Observe generic error message regardless of actual failure cause
5. Try 5k sats - should succeed

Suggested Improvements

1. Parse the LDK failure reason and map to user-friendly messages:

   • TemporaryNodeFailure → "Recipient temporarily unavailable. Try again in a moment."
   • TemporaryChannelFailure + RetriesExhausted → "No route found with sufficient liquidity. Try a smaller amount."
   • RouteNotFound → "Could not find a payment path to recipient."

2. For RetriesExhausted, consider suggesting a smaller payment amount

3. Add expandable "Technical details" section showing the actual error code for debugging

Logs / Screenshots / Recordings

• Screen recording of payment failure

Screen_Recording_20260127_110646_Bitkit.mp4

• Log file: bitkit_2026-01-27_09-14-35.log

Environment

• Device: Android
• Network: Mainnet
• Bitkit version: 174
• Recipient: Phoenix wallet