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 preview with a heartbeat while it is running. If the preview stops responding for about 17 seconds, the editor automatically detects the freeze, stops the iframe, and offers recovery options.

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

• The app's preview hangs, crashes the tab, or burns CPU on open.
• An infinite render loop reloads the editor before you can act.
• A modal or script captures input and you cannot click out.
• You just want to inspect or edit files without executing the app at all.

Two flavors

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:

• Open in Safe Mode — opens the app with ?safe=1 for this session only. The persistent flag stays off.
• Switch to Safe Mode — flips the persistent safe_mode flag on the app. Every future open is in Safe Mode until you disable it.

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 open, the editor listens for a heartbeat from the running app every second. If no heartbeat arrives for about 5 seconds, the editor concludes the preview is frozen and shows a "Preview stopped responding" message over the preview. The app itself is not stopped — it keeps running behind the message and the notice disappears by itself if the app recovers. You have four choices:

• Wait — hide the message and keep waiting. Nothing is restarted, and the notice will not come back for the next 30 seconds.
• Restart preview — reload the app from scratch.
• Turn Safe Mode on — enable the persistent safe_mode flag so the preview stays hidden while you fix the code.
• Ask the Builder to fix it — stop the frozen app, switch to the Chat tab and immediately send the App Builder agent a message with the time of the freeze and the last console output, so the agent has the context it needs. This button is disabled while the Builder is already working on a previous request, so you cannot accidentally launch a second, overlapping turn.

Once you hand the app to the Builder, the frozen 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 freezes again during the fix, it is stopped again after about 5 seconds 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

• The preview area shows a "Preview disabled — Safe Mode" placeholder with a label telling you whether it is this session only or persistent.
• A banner above the tabs reminds you Safe Mode is on.
• The Code tab works normally — edit, save, and the changes are stored.
• The Chat tab works normally — ask the agent to fix the bug or revert to an earlier version.
• The preview iframe is never mounted, so the broken code cannot execute.

Disabling Safe Mode

• Session Safe Mode — just open the app without ?safe=1 (e.g. click Design from the Apps page). The preview runs again immediately.
• Persistent Safe Mode — turn it off from any of:
  • Properties tab → Safe Mode card → toggle off
  • Apps page → ⋯ menu → Disable Safe Mode
  • The Disable Safe Mode button shown in the fullscreen Safe Mode screen

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.

Related

• Managing Apps — overview of the Apps page and Properties tab
• Overview — what the App Builder is and how preview rendering works