bug: FilePicker and UrlLauncher Service controls fail in web mode (0.81.0) — TimeoutException or "Unknown control"

[Ponce1969]

Duplicate Check

• I have searched the opened issues and there are no duplicates

Describe the bug

In Flet 0.81.0 web mode (server-side, Docker), all Service controls (FilePicker, UrlLauncher) fail to work. page.launch_url() is also deprecated and delegates to UrlLauncher internally. There is no working way to open a native file dialog or launch a URL from a Flet web app in 0.81.0.

Two distinct failure modes depending on how/when the control is registered:

Mode A — "Unknown control: FilePicker" (red error bar across all views)
Occurs when FilePicker is added to page.overlay before or during the first page.update() — e.g., in main(), MainLayout, or app.py. The JS client doesn't recognize the control because the control tree handshake hasn't completed yet.

Mode B — TimeoutException after 10s: Timeout waiting for invoke method listener
Occurs when FilePicker is created per-click (inside the button handler), added to page.overlay, page.update() called, then await picker.pick_files() called. The JS listener for FilePicker never registers in time.

Environment

Python:   3.12.13 (CPython, Linux/Docker WSL2)
Flet:     0.81.0
Platform: Web mode (flet.app with server-side rendering, accessed via browser)
Docker:   auditor_familiar_app container
OS host:  Windows 11 + WSL2

Reproduction (minimal)

import flet as ft

async def main(page: ft.Page):
    async def pick_file(_):
        picker = ft.FilePicker()
        page.overlay.append(picker)
        page.update()
        # Fails with TimeoutException after 10s in web mode:
        result = await picker.pick_files(with_data=True)
        print(result)

    page.add(ft.ElevatedButton("Pick file", on_click=pick_file))

ft.app(main, port=8550)

All registration strategies attempted (all fail in web mode)

Strategy	Result
FilePicker global in shared state	Breaks multi-session (shared across users)
FilePicker in MainLayout.did_mount()	"Unknown control" on every view
FilePicker per-click with overlay.append() + update()	TimeoutException after 10s
FilePicker in main() before first navigate()	"Unknown control" on login view
page._file_picker dynamic attribute	Object recreated on WebSocket reconnect
Per-click with asyncio.sleep(0.3) before pick_files()	TimeoutException — sleep not enough
ft.UrlLauncher().launch_url(url)	Same problem — Service needs page registration
page.launch_url(url)	Deprecated, delegates to UrlLauncher internally

Diagnostic output (check_flet.py --compat inside Docker)

FilePicker
  [OK]  ft.FilePicker exists
  [OK]  pick_files() is ASYNC
  [OK]  with_data=True available
  [OK]  FilePicker.upload() exists

URL Launcher
  [OK]  ft.UrlLauncher exists (Service — needs overlay)
  [!!]  page.launch_url() is DEPRECATED — source says "Use UrlLauncher() instead"

Page JavaScript
  [!!]  page has no JavaScript methods (run_javascript / eval_javascript)

Confirmed via inspect.getsource(ft.Page.launch_url):

@deprecated("Use UrlLauncher().launch_url() instead.", version="0.90.0", ...)
async def launch_url(self, url, ...):

Root cause hypothesis

Service controls (FilePicker, UrlLauncher) require a JS-side listener to be registered via the WebSocket handshake. In web mode with server-side rendering, this handshake does not complete reliably — the Python server calls invoke_method before the JS client has registered the listener for that specific control instance. The timeout is 10 seconds, which is never enough.

In desktop mode this works because the Flutter engine is local and the listener registration is synchronous/immediate.

Workaround implemented

We replaced FilePicker entirely with a separate FastAPI microservice that serves a native HTML <input type="file"> form. The Flet app shows the form URL in a copyable TextField, and the user opens it manually in a new browser tab. After uploading, the user clicks a "Done" button in Flet that triggers polling to retrieve the OCR result.

This works but is clearly not acceptable UX for a production app.

Expected behavior

ft.FilePicker (and ft.UrlLauncher) should work in Flet web mode (server-side) the same way they work in desktop mode. The JS listener registration should complete before pick_files() / launch_url() is awaited.

Suggestions

1. Add a await picker.ensure_ready() or similar method that waits for the JS listener to register before calling pick_files().
2. Or expose page.run_javascript() / page.eval_javascript() to allow workarounds at the app level.
3. Or document clearly which controls do NOT work in web mode and provide the recommended alternative.

Additional details

• page.run_javascript() / page.eval_javascript() do not exist on ft.Page in 0.81.0, so there is no way to work around this at the app level even with custom JS.
• The deprecation warning on page.launch_url() pointing to 0.90.0 suggests this is a known area of change — any ETA on when UrlLauncher will work reliably in web mode?

[ndonkoHenri]

Please tryout examples from our documentation:

• FilePicker
• UrlLauncher

[Ponce1969]

Thanks for the follow-up, @alexyucra. ​I have thoroughly reviewed the documentation and tested the standard implementation. However, the issue persists specifically in *server-side Web mode (Docker)*. ​The problem isn't the syntax, but the *logistical handshake* between Python and the Browser: 1. ​*Overlay Persistence:* In a routed architecture like Fleting, adding the FilePicker to page.overlay globally in main() often leads to 'Unknown control' because the JS client hasn't registered the listener at the moment of the first route change. 2. ​*Timing in Docker:* Even when registering the control correctly, the TimeoutException occurs because the WebSocket message to invoke pick_files() reaches the browser before the JS listener for that specific instance is 'ready'. This seems to be a race condition amplified by the latency of a containerized environment. 3. ​*UrlLauncher:* The same happens with UrlLauncher. Even following the 'Basic Example', it fails with a timeout in 100% of my tests under Docker/Web, while it works perfectly on Desktop. ​I’ve had to solve this by building a separate FastAPI microservice to handle file uploads via native HTML, but I believe there is a *technical gap* in Flet 0.81.0 regarding how Service controls are registered in high-latency or containerized web environments. ​I hope this feedback helps to improve the framework's reliability for web deployments! I'll be keeping an eye on future updates (0.90+) to see if the internal handshake logic is refactored." El mié, 4 mar. 2026 04:41, TheEthicalBoy ***@***.***> escribió:

…

*ndonkoHenri* left a comment (flet-dev/flet#6250) <#6250 (comment)> Please tryout examples from our documentation: - FilePicker <https://docs.flet.dev/services/filepicker/#pick-text-content-and-savedownload-it> - UrlLauncher <https://docs.flet.dev/services/urllauncher/#basic-example> — Reply to this email directly, view it on GitHub <#6250 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/A2MSU5QV2P5UAXOPGPMQAXD4O7M4LAVCNFSM6AAAAACWGG4V5CVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTSOJVHAZTOOJQGA> . You are receiving this because you authored the thread.Message ID: ***@***.***>