subservers: fail LiT startup when integrated sub-server boot fails #1183

ffranr · 2025-12-02T20:22:15Z

Treat integrated sub-servers as fatal to startup and return an error if any fail to start.
Propagate integrated sub-server startup errors to LiT so it stops launching and records the failure status.
Update docs to reflect integrated sub-servers are now critical to startup.

gemini-code-assist · 2025-12-02T20:22:35Z

Summary of Changes

Hello @ffranr, 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 significantly enhances the reliability of the LiT startup sequence by elevating the status of integrated sub-servers to critical. Previously, LiT could continue operating even if some of its integrated sub-servers failed to launch. Now, any failure in an integrated sub-server's boot process will cause LiT itself to cease its startup, ensuring that the system only reaches an operational state when all essential integrated components are functioning correctly. This change provides a more robust and predictable initialization experience.

Highlights

Critical Integrated Sub-Server Startup: Integrated sub-servers are now treated as critical components for LiT (Lightning Terminal) startup. If any integrated sub-server fails to initialize, LiT will now abort its launch process.
Error Propagation: The StartIntegratedServers function in the sub-server manager has been updated to return an error if any integrated sub-server fails to start, allowing LiT to properly handle and propagate these failures.
LiT Startup Robustness: LiT's main startup routine (terminal.go) now explicitly checks for errors returned by StartIntegratedServers and will set an errored status and halt its own startup if such failures occur.
Documentation Update: Comments within the subservers/interface.go file have been updated to reflect the new critical nature of integrated sub-servers during LiT startup.

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 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 counter productive. 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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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 modifies the startup logic to treat integrated sub-server startup failures as fatal. The changes correctly propagate errors from StartIntegratedServers up to the main start function, causing LiT to fail on startup as intended. The documentation has also been updated to reflect this new behavior. The implementation is sound, but I have one suggestion to improve the consistency of error handling.

terminal.go

ViktorT-11

Thanks for this @ffranr 🙏!

In addition to the feedback I've commented below, this new behaviour definitely needs itest coverage.

I think we actually started working on this at the same time, and I have local branch with draft code implementing this + itest coverage. If you want to, i can clean that up and push it so that you can cherry-pick that to make it more simple for you. Let me know if that'd be helpful :).

subservers/manager.go

terminal.go

ellemouton

havent actually looked at the diff here yet, just want to make a note in case: we should just make sure that the daemon still runs & ie, that the status server still gets served

subservers/manager.go

ViktorT-11

Thanks for the updates 🚀! Leaving some additional feedback in addition to @ellemouton's feedback.

itest/litd_mode_integrated_test.go

subservers/manager.go

terminal.go

lightninglabs-deploy · 2026-01-02T12:15:27Z

@ziggie1984: review reminder
@ffranr, remember to re-request review from reviewers when ready

ViktorT-11

Thanks for the updates 🙏! Looking better, but commenting of a few lines I think you should just remove to address some previously mentioned feedback.

terminal.go

- Fail LiT startup if any critical integrated sub-server fails to start. - Log non-critical sub-server startup errors without aborting startup.

- Ensure critical integrated sub-servers initialize first. - Introduce alphabetical sorting for consistent order across startup runs.

- Introduce tests for critical and non-critical sub-server startup behavior. - Ensure failures in critical servers stop startup, while non-critical failures are tolerated.

ViktorT-11

After testing this PR locally, I’ve realized that this comment isn’t really addressable with how litd is currently designed:
#1183 (comment)

The reason is that shutting down lnd will always trigger the shutdownInterceptor.ShutdownChannel() to be sent over, which in turn also shuts down litd. This behavior stems from the single-interceptor pattern we currently use in litd, which we eventually want to move away from.

As a result, I don’t think it’s possible to keep litd’s status endpoint up and running while still shutting down lnd in response to critical sub-server startup errors.

Given that, I believe the behavior introduced by this PR is effectively the best we can do until the single-interceptor pattern is addressed.

@ellemouton, do you think it’s critical that litd, and therefore the status endpoint, remains up when critical sub-servers fail on startup (which also causes lnd to shut down)? If so, we’ll need to address the single-interceptor issue first. Otherwise, can we ship this as-is for now and tackle the interceptor issue at a later stage?

ViktorT-11 · 2026-01-09T11:48:40Z

itest/litd_mode_integrated_test.go

+	// in integrated mode.
+	node, err := net.NewNode(
+		t.t, "FailFastTap", nil, false, false,
+		"--taproot-assets.rpclisten=127.0.0.1:65536",


I believe this config flag will make the node error on the config validation logic in litd, and not when tapd is attempted to be started after the wallet is unlocked.

I suggest using these config options instead, as those will actually error during tapd's startup:

taproot-assets.databasebackend=postgres taproot-assets.postgres.host=tapd-postgres.invalid

ViktorT-11 · 2026-01-09T11:50:22Z

itest/litd_mode_integrated_test.go

+	case <-time.After(15 * time.Second):
+		t.Fatalf("expected tapd startup failure to be reported")
+	}
+


Depending on @ellemouton's response to my broader question in the main review comment, we likely want to expand the test code here, to ensure that the status endpoint & lnd node is at the state we expect it to be.

ffranr self-assigned this Dec 2, 2025

gemini-code-assist bot reviewed Dec 2, 2025

View reviewed changes

terminal.go Show resolved Hide resolved

ziggie1984 self-requested a review December 3, 2025 09:14

ViktorT-11 self-requested a review December 3, 2025 12:29

ffranr force-pushed the wip/fail-startup-on-subserver-err branch from 57ee325 to 86e8ec5 Compare December 4, 2025 13:21

ffranr mentioned this pull request Dec 4, 2025

[feature]: use future/promise design for interaction with lnd lightninglabs/taproot-assets#1893

Open

ViktorT-11 reviewed Dec 5, 2025

View reviewed changes

subservers/manager.go Outdated Show resolved Hide resolved

subservers/manager.go Outdated Show resolved Hide resolved

terminal.go Show resolved Hide resolved

jtobin added this to Taproot-Assets Project Board Dec 9, 2025

github-project-automation bot moved this to 🆕 New in Taproot-Assets Project Board Dec 9, 2025

ellemouton reviewed Dec 12, 2025

View reviewed changes

ffranr force-pushed the wip/fail-startup-on-subserver-err branch 4 times, most recently from 1772099 to 0091958 Compare December 16, 2025 17:11

ffranr requested review from ViktorT-11 and ellemouton December 16, 2025 17:11

ffranr force-pushed the wip/fail-startup-on-subserver-err branch from 0091958 to 381d0b1 Compare December 18, 2025 00:17

ellemouton reviewed Dec 18, 2025

View reviewed changes

subservers/manager.go Show resolved Hide resolved

ViktorT-11 reviewed Dec 19, 2025

View reviewed changes

itest/litd_mode_integrated_test.go Show resolved Hide resolved

subservers/manager.go Show resolved Hide resolved

terminal.go Outdated Show resolved Hide resolved

terminal.go Outdated Show resolved Hide resolved

terminal.go Outdated Show resolved Hide resolved

ffranr force-pushed the wip/fail-startup-on-subserver-err branch 2 times, most recently from c910257 to 65e4e0f Compare January 6, 2026 17:19

ffranr requested review from ViktorT-11 and ellemouton January 6, 2026 17:46

ffranr moved this from 🆕 New to 👀 In review in Taproot-Assets Project Board Jan 6, 2026

ViktorT-11 reviewed Jan 7, 2026

View reviewed changes

terminal.go Outdated Show resolved Hide resolved

ffranr added 3 commits January 8, 2026 16:20

subservers: treat critical startup failures as fatal

7341bdb

- Fail LiT startup if any critical integrated sub-server fails to start. - Log non-critical sub-server startup errors without aborting startup.

subservers: sort sub-servers deterministically during integrated startup

19728cd

- Ensure critical integrated sub-servers initialize first. - Introduce alphabetical sorting for consistent order across startup runs.

itest: add integrated-mode fail-fast test for tapd startup errors

e598a00

ffranr added 3 commits January 8, 2026 16:20

itest: add integrated-mode non-critical sub-server startup failure test

d511093

subservers: add unit tests for integrated server startup logic

2b67159

- Introduce tests for critical and non-critical sub-server startup behavior. - Ensure failures in critical servers stop startup, while non-critical failures are tolerated.

docs: add release note

3368bcf

ffranr force-pushed the wip/fail-startup-on-subserver-err branch from 65e4e0f to 3368bcf Compare January 8, 2026 16:20

ffranr requested a review from ViktorT-11 January 8, 2026 16:39

ViktorT-11 reviewed Jan 9, 2026

View reviewed changes

subservers: fail LiT startup when integrated sub-server boot fails #1183

Are you sure you want to change the base?

subservers: fail LiT startup when integrated sub-server boot fails #1183

Uh oh!

Conversation

ffranr commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Dec 2, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

ViktorT-11 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ellemouton left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ViktorT-11 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lightninglabs-deploy commented Jan 2, 2026

Uh oh!

ViktorT-11 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ViktorT-11 left a comment

Choose a reason for hiding this comment

Uh oh!

ViktorT-11 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

ViktorT-11 Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ffranr commented Dec 2, 2025 •

edited

Loading

ViktorT-11 left a comment •

edited

Loading