fix: Handle read-only filesystem when updating starter project files

[devbyteai]

Summary

Fixes #11145 - Starter projects fail to load on Kubernetes when readOnlyRootFilesystem: true.

Problem

When deploying Langflow 1.7.1 on Kubernetes with security hardening (readOnlyRootFilesystem: true), the application crashes during startup with:

Failed to acquire lock for starter projects: [Errno 30] Read-only file system:
'/app/.venv/lib/python3.12/site-packages/langflow/initial_setup/starter_projects/Basic Prompt Chaining.json'

Root Cause Analysis

The error message is misleading - this is NOT a lock file issue. The actual problem:

1. Lock file uses tempfile.gettempdir() (line 212 in main.py) - this is writable
2. Real bug: update_project_file() in setup.py tries to write updated project data back to JSON files in the package installation directory
3. Package directory is read-only in containerized environments following security best practices

Solution

Wrap the file write operation in a try-except block that catches OSError and logs it as debug instead of failing. The database is the source of truth for project data - file updates are optional convenience for development environments.

try:
    async with async_open(str(project_path), "w", encoding="utf-8") as f:
        await f.write(orjson.dumps(project, option=ORJSON_OPTIONS).decode())
    await logger.adebug(f"Updated starter project {project['name']} file")
except OSError as e:
    # Handle read-only filesystem (common in containerized environments)
    await logger.adebug(
        f"Could not update starter project file {project['name']} (read-only filesystem): {e}. "
        "This is expected in containerized environments with read-only root filesystem."
    )

Impact Analysis

Components Verified

1. update_project_file() - Now handles read-only gracefully
2. load_starter_projects() - Read-only, unaffected
3. template_search.py - Read-only, unaffected
4. Lock file in main.py - Uses tempdir, unaffected

What This Does NOT Affect

1. Database operations (unchanged - this is the source of truth)
2. Starter project loading from files (read-only, unchanged)
3. Writable filesystem environments (still updates files as before)
4. Any other component or plugin

Breaking Changes

None. This change is fully backward compatible:
1. Writable filesystems: Files still updated as before
2. Read-only filesystems: Gracefully skipped with debug log

Testing

Test 1: Writable Filesystem (Development)

- Start langflow with update_starter_projects=True
- Expected: Project files updated normally
- Result: Pass

Test 2: Read-Only Filesystem (Kubernetes)

- Deploy with readOnlyRootFilesystem: true
- Expected: No crash, starter projects load from database
- Result: Pass

Test 3: Database as Source of Truth

- Modify starter project in database
- Restart langflow
- Expected: Database version used, file write skipped gracefully
- Result: Pass

Test 4: Logging Verification

- Enable debug logging
- Run on read-only filesystem
- Expected: Debug message about skipped file update
- Result: Pass

Checklist

- Reproduced the original issue
- Verified fix resolves the issue
- Tested writable filesystem scenario (backward compatibility)
- Tested read-only filesystem scenario
- No breaking changes
- Code follows existing patterns
- Added docstring explaining the behavior

<!-- This is an auto-generated comment: release notes by coderabbit.ai -->

## Summary by CodeRabbit

* **Bug Fixes**
* Enhanced error handling for read-only filesystems to prevent crashes. The application now gracefully manages file write failures in constrained environments while preserving data integrity. Added diagnostic logging to provide visibility into read-only scenarios.

* **Documentation**
* Updated documentation with details about read-only filesystem handling.

<sub>✏️ Tip: You can customize this high-level summary in your review settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[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.

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

Walkthrough

The change adds error handling to gracefully manage read-only filesystem scenarios when updating starter project files, catching OSError exceptions during file writes to prevent crashes in containerized environments with restricted filesystem permissions.

Changes

Cohort / File(s)	Summary
Read-only filesystem error handling src/backend/base/langflow/initial_setup/setup.py	Wraps file write operation in update_project_file with try/except OSError block to handle read-only filesystems gracefully. Adds debug logging for read-only scenarios and docstring documentation. Maintains existing successful write path and logging behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Pre-merge checks and finishing touches

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Test Coverage For New Implementations	❌ Error	The PR modifies update_project_file() to handle read-only filesystems but includes no accompanying test files to verify the fix works correctly or prevent regressions.	Add unit tests covering: (1) normal write path, (2) OSError exception handling for read-only filesystem, (3) debug log verification. Include integration test for database fallback loading when filesystem writes fail.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.
Test Quality And Coverage	⚠️ Warning	PR lacks specific unit tests validating OSError handling for read-only filesystem scenarios despite implementation being sound.	Add unit tests using pytest mocking to simulate OSError on file write, verify exception handling, and test both writable and read-only filesystem paths.
Test File Naming And Structure	❓ Inconclusive	Cannot locate or verify test files for the setup.py changes in this PR. Repository exploration found the modified setup.py but no corresponding test files with proper naming conventions (test_*.py or *_test.py) for validating the read-only filesystem handling and other functionality changes.	Provide the list of all test files added or modified in this PR, including their content, to verify proper naming conventions, pytest structure, and test coverage for the update_project_file() function and edge cases.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title clearly and specifically describes the main change: handling read-only filesystems when updating starter project files, which directly addresses the issue reported in #11145.
Linked Issues check	✅ Passed	The PR successfully addresses issue #11145 by wrapping the file write in try/except OSError to gracefully handle read-only filesystems, allowing starter projects to load from the database without crashes.
Out of Scope Changes check	✅ Passed	All changes are scoped to the update_project_file function with only internal error handling and docstring additions; no unrelated modifications are present.
Excessive Mock Usage Warning	✅ Passed	The PR introduces a minimal change wrapping file write operations in try-except to handle OSError gracefully. Existing test infrastructure uses mocks appropriately without over-mocking.

---

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 and usage tips.}