modal race condition problem

[krisztianlukacs]

Textual Framework Bug Report: Modal Race Condition with push_screen and dismiss

Summary

When using ModalScreen with push_screen and dismiss, there is a race condition where the await push_screen() returns None immediately, before the user has a chance to interact with the modal (e.g., click Save/Cancel buttons). This makes it impossible to retrieve data from modal dialogs reliably.

Environment

• Textual Version: [Latest as of 2025-06-28]
• Python Version: 3.x
• Operating System: Linux

Expected Behavior

When using await push_screen(MyModal()), the code should wait until the modal is dismissed (either via Save or Cancel), and the returned value should be the data passed to dismiss().

Actual Behavior

The await push_screen() returns None immediately, without waiting for user interaction. The modal remains visible and functional, but the calling code receives None instead of the expected data when the user later clicks Save.

Reproducible Example

Modal Class

from textual.screen import ModalScreen
from textual.widgets import Button, TextArea, Label, Container, Horizontal
from textual.app import ComposeResult
from textual import on
import json
from typing import Optional, Dict, Any

class ConfigEditModal(ModalScreen[Optional[Dict[str, Any]]]):
    """Modal for editing configuration JSON"""
    
    def __init__(self, config_data: Dict[str, Any], title: str = "Edit Configuration"):
        super().__init__()
        self.config_data = config_data
        self.modal_title = title
    
    def compose(self) -> ComposeResult:
        with Container(id="config-edit-modal"):
            yield Label(self.modal_title, id="modal-title")
            yield TextArea(
                json.dumps(self.config_data, indent=2),
                language="json",
                id="config-editor"
            )
            with Horizontal(id="modal-buttons"):
                yield Button("Save", variant="primary", id="save-config")
                yield Button("Cancel", variant="default", id="cancel-config")
    
    @on(Button.Pressed, "#save-config")
    def save_config(self):
        editor = self.query_one("#config-editor", TextArea)
        try:
            config_data = json.loads(editor.text)
            print(f"MODAL: About to call dismiss with data: {len(str(config_data))} chars")
            self.dismiss(config_data)  # This should return data to the caller
            print(f"MODAL: dismiss() called successfully")
        except json.JSONDecodeError as e:
            self.notify(f"Invalid JSON: {e}", severity="error")
    
    @on(Button.Pressed, "#cancel-config")
    def cancel_config(self):
        print(f"MODAL: About to call dismiss with None")
        self.dismiss(None)

Main Application Code

from textual.app import App
from textual.widgets import Button
from textual import on

class TestApp(App):
    
    @on(Button.Pressed, "#test-modal")
    async def test_modal(self):
        """Test the modal race condition"""
        print("APP: About to call push_screen")
        
        result = await self.push_screen(
            ConfigEditModal({"test": "data"}, "Test Modal")
        )
        
        print(f"APP: Modal returned, result type: {type(result)}, is None: {result is None}")
        
        if result:
            print(f"APP: Received data: {result}")
        else:
            print("APP: No data received (race condition occurred)")

Steps to Reproduce

1. Run the application with the above code
2. Click the button to open the modal
3. Observe console output: "APP: Modal returned, result type: <class 'NoneType'>, is None: True" appears immediately
4. Edit the JSON in the modal
5. Click the "Save" button
6. Observe console output: "MODAL: About to call dismiss with data: X chars" and "MODAL: dismiss() called successfully" appear much later
7. The result in the main app is always None, even though the modal successfully called dismiss() with data

Debug Timeline Example

[21:18:42] APP: About to call push_screen
[21:18:42] APP: Modal returned, result type: <class 'NoneType'>, is None: True
[21:18:42] APP: No data received (race condition occurred)
... (user interacts with modal for ~2 minutes)
[21:20:06] MODAL: About to call dismiss with data: 772 chars  
[21:20:06] MODAL: dismiss() called successfully

Impact

This race condition makes it impossible to:

• Create data entry modals that return user input
• Implement confirmation dialogs that return user choices
• Build complex modal workflows that depend on modal results

Workaround

We had to implement a callback mechanism to work around this issue:

class ConfigEditModal(ModalScreen[Optional[Dict[str, Any]]]):
    def __init__(self, config_data, title="Edit Configuration", save_callback=None):
        super().__init__()
        self.config_data = config_data
        self.modal_title = title
        self.save_callback = save_callback  # Workaround callback
    
    @on(Button.Pressed, "#save-config")
    def save_config(self):
        editor = self.query_one("#config-editor", TextArea)
        try:
            config_data = json.loads(editor.text)
            
            # Use callback instead of dismiss to avoid race condition
            if self.save_callback:
                self.save_callback(config_data)
                self.dismiss(True)  # Just signal completion
            else:
                self.dismiss(config_data)  # Original mechanism (broken)
        except json.JSONDecodeError as e:
            self.notify(f"Invalid JSON: {e}", severity="error")

# Usage with workaround:
async def edit_config(self):
    def save_callback(config_data):
        # Handle the data directly here
        self.handle_config_save(config_data)
    
    await self.push_screen(
        ConfigEditModal(self.config_data, "Edit Config", save_callback=save_callback)
    )
    # No need to handle return value since callback handles everything

Expected Fix

The await push_screen() should properly wait for the modal to be dismissed before returning the value passed to dismiss(). The async/await mechanism should handle the modal lifecycle correctly, ensuring that:

1. push_screen() waits until dismiss() is called
2. The value passed to dismiss() is properly returned to the awaiting code
3. The timing is deterministic and not subject to race conditions

Additional Notes

This issue appears to be related to the async event loop handling in Textual's modal system. The push_screen method returns before the modal's event handlers have a chance to execute, breaking the expected async/await flow.

The problem is consistently reproducible and affects any modal that needs to return data to the calling code.

[github-actions[bot]]

We found the following entry in the FAQ which you may find helpful:

• How do I center a widget in a screen?

Feel free to close this issue if you found an answer in the FAQ. Otherwise, please give us a little time to review.

This project is developed and maintained by Will McGugan. Consider sponsoring Will's work on this project (and others).

This is an automated reply, generated by FAQtory

[willmcgugan]

Thank you for the big report. This is expected behaviour. The guide explains how to get the result in some detail. https://textual.textualize.io/guide/screens/#returning-data-from-screens