Safe Mode

Recover an app that freezes the browser or loops in preview

What it is

Safe Mode opens an app in the App Builder without running its live preview. The app's files are loaded so you can edit them in the Code tab and chat with the agent to revert or fix the problem — but the iframe that runs the app is never mounted, so a broken app cannot freeze the page, loop infinitely, or trap you out of your own work.

The editor also watches the visible preview with a heartbeat while it is running. It allows 30 seconds for startup, then offers recovery options after about 15 seconds without a response.

Use it whenever an app becomes unresponsive in the editor and you can no longer reach the Properties, Code, or Chat tabs through the normal preview view.

When to use it

Two flavors

Mode Where it lives Scope Best for
Session Safe Mode ?safe=1 URL parameter This tab only — gone on next normal open A one-time rescue so you can edit and ship a fix
Persistent Safe Mode safe_mode flag on the app Every open, every device, until turned off Apps that need ongoing work before they're safe to run again

Both flavors block the preview the same way. The difference is only how long the block lasts.

Activating Safe Mode

From the Apps page (recommended)

Go to /apps, open the ⋯ (More) menu on the app's row, and choose one of:

Apps with the persistent flag on show a Safe Mode badge next to their name on this page.

From the URL

Append ?safe=1 to any /app/:id URL:

/app/cbd1fec9-806a-4d84-82ff-f2cbb3db79d4?safe=1

This works even if you cannot reach the Apps page menu — bookmark it for emergencies.

From inside the app (Properties tab)

If you can still reach the Properties tab, scroll to the Safe Mode card and flip the switch. This sets the persistent flag.

Automatic freeze detection

When the App Builder preview is visible, the editor listens for a heartbeat from the running app every second. A fresh preview gets 30 seconds to start and settle. After that, about 15 continuous seconds without a heartbeat shows a "Preview is taking unusually long" message. Monitoring pauses when you open another Builder tab or hide the browser tab, and resumes with a fresh observation window.

The heartbeat uses the app's browser UI thread. A missing heartbeat therefore means the app may be busy or stuck; it is not proof of an infinite loop. The app itself is not stopped — it keeps running behind the message and the notice disappears by itself if it recovers. You have four choices:

Once you hand the app to the Builder, the suspected stalled preview is stopped completely — it can no longer make the browser complain about an unresponsive page. As soon as the Builder saves a change, the preview starts again automatically so the agent can see and test the result. If the app stalls again during the fix, it is stopped again after the conservative detection window and a fresh report (with the newest console output) is available for the next "Ask the Builder to fix it" click. You can always use Restart preview to reload the app manually at any point.

The freeze state and the last console logs are saved to the app's diagnostics, so the agent can see them when you ask for help.

The preview also runs isolated from the editor, so an app stuck in an endless loop keeps the editor itself responsive — you can still chat, edit code and switch tabs while the frozen preview is being stopped. Once an app has frozen, it is never run inside the editor page itself; if the isolated preview cannot start, you get a "Preview could not be started safely" message instead.

What you see in Safe Mode

Disabling Safe Mode

Avoiding confusion when both apply

If a one-time ?safe=1 session is active while the persistent toggle is off, the Properties card shows an amber notice explaining the situation. Closing the tab or opening the app without the URL parameter is enough — you don't need to touch the toggle.