htlcswitch: adding temporary_channel_failure

[murraystewart96]

This commit modifies the behaviour when a node can't forward an HTLC due to a temporary channel failure. Rather than return unknown_next_peer which instructs the sender to fully remove the channel from the graph temporary_channel_failure gives the sender the change to handle it more gracefully. We also return the latest channel update to the sender.

Change Description

Description of change / link to associated issue.

Steps to Test

Steps for reviewers to follow to test the change.

Pull Request Checklist

Testing

• Your PR passes all CI checks.
• Tests covering the positive and negative (error paths) are included.
• Bug fixes contain tests triggering the bug to prevent regressions.

Code Style and Documentation

• The change is not insubstantial. Typo fixes are not accepted to fight bot spam.
• The change obeys the Code Documentation and Commenting guidelines, and lines wrap at 80.
• Commits follow the Ideal Git Commit Structure.
• Any new logging statements use an appropriate subsystem and logging level.
• Any new lncli commands have appropriate tags in the comments for the rpc in the proto file.
• There is a change description in the release notes, or [skip ci] in the commit message for small changes.

📝 Please see our Contribution Guidelines for further guidance.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request improves the robustness of HTLC forwarding by refining how nodes communicate channel failures. By replacing the generic unknown_next_peer error with a more descriptive temporary_channel_failure, the sender is provided with the latest channel update, enabling better routing decisions and reducing unnecessary graph pruning.

Highlights

• Error Handling Improvement: Updated the HTLC forwarding logic to return a temporary_channel_failure instead of unknown_next_peer when a link is not eligible for forwarding.
• Channel Update Propagation: Implemented a new helper method that includes the latest channel update in the failure message, allowing the sender to update their routing graph more effectively.
• Test Updates: Updated existing multi-hop forwarding tests to reflect the change in expected error codes.

New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request updates the HTLC switch to return a temporary channel failure containing the latest channel update instead of an unknown next peer error when a forwarding link is not eligible. The review feedback suggests adding a defensive check to ensure that the fetched channel update is not nil before returning, preventing potential nil pointer dereferences.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[github-actions]

🔴 PR Severity: CRITICAL

htlcswitch package | 1 file | 31 lines changed

🔴 Critical (1 file)

• htlcswitch/switch.go - Core HTLC switch logic; modifications here affect HTLC forwarding and the payment routing state machine

Analysis

This PR modifies htlcswitch/switch.go, which is part of the htlcswitch package — the heart of HTLC forwarding and payment routing in lnd. Changes here can directly affect in-flight payments, routing decisions, and channel state transitions. Even small changes in this package can have significant impact on payment reliability and fund safety, warranting expert review.

The test file (htlcswitch/switch_test.go) was excluded from severity bump calculations. The non-test change is limited to 1 file and 31 lines, so no severity bump rules were triggered — but the base classification is already CRITICAL due to the package path.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}
<!-- pr-severity-bot -->