Page will refresh after a network offline and online

[programus]

First Check

• I added a very descriptive title here.
• This is not a Q&A. I am sure something is wrong with NiceGUI or its documentation.
• I used the GitHub search to find a similar issue and came up empty.

Example Code

# copy from https://nicegui.io/documentation/page#wait_for_client_connection

import asyncio
from nicegui import ui

@ui.page('/wait_for_connection')
async def wait_for_connection():
    ui.label('This text is displayed immediately.')
    await ui.context.client.connected()
    await asyncio.sleep(2)
    ui.label('This text is displayed 2 seconds after the page has been fully loaded.')

@ui.page('/')
def page():
    ui.link('wait for connection', wait_for_connection)

ui.run()

Description

1. Access https://nicegui.io/wait_for_connection , which is running the example code.
2. Break the network connection to the server for several seconds. (Or simulate it by browser's dev tool > Network tab)
3. Restore the network connection again.
4. The page would refresh automatically with a message, reloading because handshake failed for clientId <uuid> in the console. While I expect it remains the same without any refreshing since I haven't touched it at all and nothing happening should be normal.

Usually, this does not affect so much, but this would be critical for the users with an unstable Internet connection.

I suppose all the code for a page should be only triggered while user access the specified page.

NiceGUI Version

3.1.0 (I am not sure whether this is the same as the NiceGUI document)

Python Version

3.12.10 (I am not sure whether this is the same as the NiceGUI document)

Browser

Other, Chrome

Operating System

macOS

Additional Context

No response

[evnchn]

Hello @programus

In short, NiceGUI spawns a Client one-on-one with the browser for the logic and interactivity. That client is deleted due to too long time, and so browser reloads and the code is executed again as such.

You may want to change your code to not be dependent on the number of times the page function is ran.

[programus]

@evnchn Thank you for your response. I found that this refreshing is not related to the await ui.context.client.connected(), it happens even I removed it. So I changed the description.

Is there any way to disable the reloading until there is any interaction triggered by javascript or user between the client and the server?

And is there any other cases the client is deleted?

Actually I found this because one of the apps I built by NiceGUI always reload itself regularly, even the network is not broken.

[evnchn]

https://github.com/zauberzeug/nicegui/blob/main/nicegui/client.py#L398-L412

Sorry non-configurable right now, client can last 60s before it's gone.

[programus]

And is there any other cases the client is deleted?

Actually I found this because one of the apps I built by NiceGUI always reload itself regularly, even the network is not broken.

What could be the reason of this case?

[evnchn]

Do you have some background repetitive process which blocks the main thread (Did you use sleep? Did you use requests?)

That's a big no-no for asyncio based stuff. Most probably AI can help you screen for such issues and fix it.

To clarify: you can't block the main thread anywhere, background nor foreground.

[programus]

Do you have some background repetitive process which blocks the main thread (Did you use sleep? Did you use requests?)

I don't think there is any process blocks the main thread. I am using requests, but all of them are triggered by a user action. But the page reloads even I just leave it there for about 10 minutes. Furthermore, all the requests are in async functions.

To clarify: you can't block the main thread anywhere, background nor foreground.

Do you mean the main thread here is like a traditional GUI message/event loop?

client can last 60s before it's gone.

If this is the case, why does the page reload even after just a few seconds disconnection? I think you can reproduce the reloading with just less than 10 sec disconnection.

[evnchn]

Furthermore, all the requests are in async functions.

Wrapping blocking functions in async function doesn't make it not block, unfortunately.

And the blocking, I refer to asyncio. Any function which waits (for IO, or just for sakes) without using some sort of asyncio mechanism will block the main thread.

[programus]

Furthermore, all the requests are in async functions.

Wrapping blocking functions in async function doesn't make it not block, unfortunately.

And the blocking, I refer to asyncio. Any function which waits (for IO, or just for sakes) without using some sort of asyncio mechanism will block the main thread.

My code is very similar with API requests example, just using requests instead of httpx. Wrapping the http request in an async function and call it without await in a button click handler. Does this also block the main thread?

If this also block it, does background_tasks.create() solve the blocking problem?

But I don't think the blocking (even there are some) is the reason of the reloading problem since the refreshing happens even there is no API request triggered.

[rodja]

just using requests instead of httpx

That is exactly the problem. Please read https://github.com/zauberzeug/nicegui/wiki/FAQs#why-is-my-long-running-function-blocking-ui-updates

[evnchn]

exactly the problem

He's claiming that even when nothing is ran, disconnects happen, so it may not be the whole problem.

Nevertheless, this is still one big problem.

[falkoschindler]

@programus I'm confused about your minimum example:

• First you said it's related to awaiting the client connection.
• Then it isn't related anymore. (Which leaves basically a hello-world page.)
• Then you mention synchronous web requests.
• But they are user-triggered; the problem occurs without them.

Can you reproduce the problem with a minimum app like the following?

from nicegui import ui

@ui.page('/')
def page():
    ui.label('Hello')

ui.run()

[programus]

@falkoschindler Sorry for the changing the description.

I confirmed the reload by the minimum example also. To make the reload more observable, I would like to share an alternative minimum example by changing the static Hello label to a current time. (The static Hello code also reloads by the following steps.)

from nicegui import ui
from datetime import datetime

@ui.page('/')
def page():
    ui.label(f'Current time: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')

ui.run()

Here is the terminal log for the confirmation:

~/workspace/tmp
[11-07 14:08:29]❯ mkdir nicegui-reload-confirm

~/workspace/tmp
[11-07 14:08:41]❯ cd nicegui-reload-confirm

~/workspace/tmp/nicegui-reload-confirm
[11-07 14:08:43]❯ uv init
Initialized project `nicegui-reload-confirm`

~/workspace/tmp/nicegui-reload-confirm on  main [?] is 📦 v0.1.0 via 🐍 v3.12.7
[11-07 14:08:45]❯ cat << EOF > main.py
∙ from nicegui import ui
from datetime import datetime

@ui.page('/')
def page():
    ui.label(f'Current time: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')

ui.run()
∙ EOF

~/workspace/tmp/nicegui-reload-confirm on  main [?] is 📦 v0.1.0 via 🐍 v3.12.7
[11-07 14:09:02]❯ cat main.py
from nicegui import ui
from datetime import datetime

@ui.page('/')
def page():
    ui.label(f'Current time: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}')

ui.run()

~/workspace/tmp/nicegui-reload-confirm on  main [?] is 📦 v0.1.0 via 🐍 v3.12.7
[11-07 14:09:19]❯ uv add nicegui==3.1.0
Resolved 49 packages in 106ms
Installed 47 packages in 71ms
 + aiofiles==25.1.0
 + aiohappyeyeballs==2.6.1
 + aiohttp==3.13.2
 + aiosignal==1.4.0
 + annotated-doc==0.0.3
 + annotated-types==0.7.0
 + anyio==4.11.0
 + attrs==25.4.0
 + bidict==0.23.1
 + certifi==2025.10.5
 + click==8.3.0
 + docutils==0.22.3
 + fastapi==0.121.0
 + frozenlist==1.8.0
 + h11==0.16.0
 + httpcore==1.0.9
 + httptools==0.7.1
 + httpx==0.28.1
 + idna==3.11
 + ifaddr==0.2.0
 + itsdangerous==2.2.0
 + jinja2==3.1.6
 + markdown2==2.5.4
 + markupsafe==3.0.3
 + multidict==6.7.0
 + nicegui==3.1.0
 + orjson==3.11.4
 + propcache==0.4.1
 + pydantic==2.12.4
 + pydantic-core==2.41.5
 + pygments==2.19.2
 + python-dotenv==1.2.1
 + python-engineio==4.12.3
 + python-multipart==0.0.20
 + python-socketio==5.14.3
 + pyyaml==6.0.3
 + simple-websocket==1.1.0
 + sniffio==1.3.1
 + starlette==0.49.3
 + typing-extensions==4.15.0
 + typing-inspection==0.4.2
 + uvicorn==0.38.0
 + uvloop==0.22.1
 + watchfiles==1.1.1
 + websockets==15.0.1
 + wsproto==1.2.0
 + yarl==1.22.0

~/workspace/tmp/nicegui-reload-confirm on  main [?] is 📦 v0.1.0 via 🐍 v3.12.7
[11-07 14:09:33]❯ uv run main.py
NiceGUI ready to go on http://localhost:8080, http://**********:8080, http://**********:8080, http://192.168.0.100:8080, http://**********:8080, and http://**********:8080
http://localhost:8080/.well-known/appspecific/com.chrome.devtools.json not found
http://127.0.0.1:8080/sw.js not found
http://localhost:8080/sw.js not found
http://localhost:8080/.well-known/appspecific/com.chrome.devtools.json not found
http://localhost:8080/sw.js not found
http://localhost:8080/.well-known/appspecific/com.chrome.devtools.json not found
http://localhost:8080/sw.js not found

And this is the screen recording of the browser:

This is also confirmed on NiceGUI 3.2.0.

For the case it reloads without any network disconnection case, I have to ask for permission to put the minimum example to a server with the same configuration, I will comment here once I completed the setup and confirmed whether it also happens.

[falkoschindler]

Thanks, @programus, that's a great reproduction!

Maybe it's just bad timing? By default the timeout for reconnecting to the server is only 3 seconds. You can try increasing it and see if the problem persists:

@ui.page('/', reconnect_timeout=30)

or

ui.run(reconnect_timeout=30)