fix(initial_setup): preserve variable bindings when loading flows from disk

[erichare]

Summary

• Preserve global-variable bindings configured in the UI when an existing flow is reloaded from LANGFLOW_LOAD_FLOWS_PATH.
• Keep explicit bindings and all non-binding flow structure from the mounted file authoritative.
• Apply the same preservation recursively to grouped/nested flows.
• Add LANGFLOW_LOAD_FLOWS_PRESERVE_VARIABLE_BINDINGS (default true) with a false opt-out for the previous blind-overwrite behavior.

Root cause

Startup re-imports every mounted flow JSON and replaces the existing row's entire Flow.data value. Global-variable selections are stored only in each component field's value and load_from_db attributes inside that JSON tree, so UI-configured bindings were erased on every restart even though the underlying variables remained in the database.

Fix

When updating an existing flow, merge only real variable bindings (load_from_db: true with a non-empty variable name) from the stored flow into matching nodes and fields in the incoming data. Node and field matching uses stable IDs/names, explicit incoming bindings win, new or removed nodes follow the file, and empty default secret fields are not treated as bindings.

Tests

• 20 passed — src/backend/tests/unit/initial_setup/test_upsert_flow_from_file.py
• 28 passed — src/lfx/tests/unit/services/settings/test_settings_composition.py (isolated src/lfx environment)
• Ruff formatting and lint checks for all changed Python files
• Pre-commit hooks, including detect-secrets

Summary by CodeRabbit

• New Features

  • Added an option to preserve database-backed variable bindings when reloading flows from files.
  • Preservation is enabled by default and supports nested flows.
  • Added an embedded-mode setting to hide getting-started progress UI.

• Documentation

  • Documented the new flow-reload and embedded-mode configuration options.

• Bug Fixes

  • Flow reloads now retain existing variable bindings while still applying other file-based updates.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fc2404d3-292a-49ea-9248-b5bad5fd781d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

Flow reloads now preserve existing database-backed variable bindings by default, with an environment-configurable opt-out. The merge handles nested flows and is covered by expanded upsert tests. Documentation also adds the embedded-mode onboarding-progress flag.

Changes

Flow binding preservation

Layer / File(s)	Summary
Settings contract and documentation src/lfx/src/lfx/services/settings/groups/components.py, src/lfx/tests/unit/services/settings/test_settings_composition.py, docs/docs/Develop/environment-variables.mdx	Adds load_flows_preserve_variable_bindings, defaulting to True, with environment-variable parsing and documentation.
Upsert merge implementation src/backend/base/langflow/initial_setup/setup.py	Merges existing database-backed variable bindings into incoming flow data, recursively handling nested flows when preservation is enabled.
Binding preservation validation src/backend/tests/unit/initial_setup/test_upsert_flow_from_file.py	Tests preserved bindings, explicit file overrides, nested groups, missing nodes, disabled preservation, and empty database defaults.

Embedded-mode documentation

Layer / File(s)	Summary
Embedded-mode flag documentation docs/docs/Develop/environment-variables.mdx	Documents LANGFLOW_HIDE_GETTING_STARTED_PROGRESS as an independent flag for hiding onboarding progress UI.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FlowFile
  participant upsert_flow_from_file
  participant Settings
  participant ExistingFlow
  FlowFile->>upsert_flow_from_file: incoming flow data
  upsert_flow_from_file->>Settings: read preservation setting
  upsert_flow_from_file->>ExistingFlow: read existing flow data
  upsert_flow_from_file->>upsert_flow_from_file: merge variable bindings
  upsert_flow_from_file->>ExistingFlow: update flow

Loading

Possibly related PRs

• langflow-ai/langflow#13132: Changes flow matching in the same upsert path, while this PR changes data merging after a flow is matched.

Suggested reviewers: ogabrielluiz, jordanrfrazier, aimurphy, andifilhohub, mendonk

🚥 Pre-merge checks | ✅ 9

✅ Passed checks (9 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main behavior change in flow loading.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Test Coverage For New Implementations	✅ Passed	The PR adds targeted backend regression tests for flow re-import binding preservation and unit tests for the new settings field/env var, all following naming conventions.
Test Quality And Coverage	✅ Passed	Tests cover preserve/override/disable/nested/default cases and validate settings env-var/defaults with async pytest patterns; they assert behavior, not smoke.
Test File Naming And Structure	✅ Passed	Both changed test files follow pytest naming/structure, use descriptive test names and fixtures/context managers, and cover positive and negative cases appropriately.
Excessive Mock Usage Warning	✅ Passed	The new tests rely on real DB/settings behavior; no mock objects are used, and monkeypatch is only used to set env vars.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/preserve-load-flow-variable-bindings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Test Coverage Advisor

No source changes detected without accompanying tests. Thanks for keeping coverage up! 🎉

Advisory check only — never blocks merge.

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.75%. Comparing base (4e42308) to head (089d512).
⚠️ Report is 1 commits behind head on release-1.11.0.

Files with missing lines	Patch %	Lines
src/backend/base/langflow/initial_setup/setup.py	87.09%	8 Missing ⚠️

Additional details and impacted files

@@                Coverage Diff                 @@
##           release-1.11.0   #14053      +/-   ##
==================================================
- Coverage           60.89%   60.75%   -0.15%     
==================================================
  Files                2375     2375              
  Lines              234063   234125      +62     
  Branches            32988    33083      +95     
==================================================
- Hits               142532   142241     -291     
- Misses              89820    90173     +353     
  Partials             1711     1711              

Flag	Coverage Δ
backend	67.10% <87.09%> (-0.66%)	⬇️
frontend	59.45% <ø> (-0.05%)	⬇️
lfx	59.26% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...lfx/src/lfx/services/settings/groups/components.py	95.45% <100.00%> (+0.14%)	⬆️
src/backend/base/langflow/initial_setup/setup.py	60.58% <87.09%> (+1.12%)	⬆️

... and 80 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Build successful! ✅
Deploying docs draft.
Deploy successful! View draft

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	46.55% (65631/140962)	70.21% (9148/13028)	44.95% (1505/3348)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
5372	0 💤	0 ❌	0 🔥	19m 19s ⏱️

[Cristhianzl]

lgtm