Build and preview troubleshooting

When a build fails or your preview does not load, start with the first visible error and work through the recovery path for that symptom. This page covers the App Viewer, Preview, build errors, and the steps to take before reporting an issue.

Start here

After an Agent finishes a task, the App Viewer loads your app. The Terminal shows task activity and errors, while the App Viewer toolbar gives you a Reload App Viewer control, a device-view switch, an option to open the preview in a new tab, and the Console.

1. Save the latest change and wait for the current task or build to finish.
2. Select Reload App Viewer once if the preview looks stale or remains on a loading screen.
3. Open the preview in a new tab if the embedded App Viewer is stuck or unresponsive.
4. Open Console and copy the first visible error. Keep the project link and the time of the failure.

When the build fails

Try Resolve first

When Atoms detects a build problem, an Issue Report notification appears in the bottom-left corner. If the notification includes Resolve, start one repair attempt before taking another action.

1. Select Resolve and wait for the current attempt to finish.
2. Do not select Resolve again while it is running.
3. If the attempt does not finish, record the visible status and continue with the reporting steps below. Do not start another Resolve attempt.
4. When the attempt finishes, check the refreshed preview. If it does not update, refresh the browser once.
5. Repeat the action that caused the problem. If the problem remains, expand the Issue Report and continue with the reporting steps below.

Build error or missing dependency

If the Preview panel shows a build error, a red error banner, or a message about a missing package, use the exact message to narrow the next step.

1. Open Console and copy the full error message that is visible there.
2. If Resolve is available, use it once and wait for the attempt to finish.
3. If there is no Resolve button, paste the exact error into Project chat and ask the Agent to fix that build error.
4. If the error started after a specific change, open History and compare the current version with the last working version.
5. If the error is difficult to isolate, Remix from the last stable version and reapply changes incrementally.

Errors that mention App Viewer, the startup script, Publish, a deploy record, or a third-party package’s internal files may indicate a platform issue. Include the complete error message when you contact Support.

Build remains in progress

Check the Terminal for current task activity before retrying. If the task or build is still running, wait for it to finish. If it remains in progress after the current attempt ends, record the status, timestamp, project link, and any visible error details, then report the issue.

When the Preview or App Viewer does not load

Loading screen or unresponsive preview

First check whether only the embedded App Viewer is affected, or whether the Preview URL and published site are affected too.

1. Confirm whether the current task or build is still running.
2. Select Reload App Viewer once.
3. Open the Preview in a new browser tab.
4. Test the same URL in an Incognito window.
5. If the last known working version loads, compare it with the recent change that introduced the problem.

If the product explicitly reports an insufficient Cloud & AI balance or a suspended app, open Settings → Cloud & AI and review that status. Do not top up based on a blank screen alone.

Blank or incomplete preview

Check whether the blank screen affects the entire app or only one page or component. If only one area is affected, use the page selector to open that page directly and repeat the smallest user journey that reaches it. If the entire preview is blank, return to the build result and resolve the first build or runtime error before testing again.

Record any Console or Network error without sharing cookies, tokens, or secret values. If the issue continues, include the sanitized error details in your report.

Preview shows an older version

Preview and the published site are separate channels. Make sure the latest changes were saved and the latest build completed before refreshing the preview. Reopen the Preview after the build completes. If it still shows older content, compare the current version with the last known working version in History.

When the preview looks wrong

Interactions or navigation do not work

A page that renders is not the same as a page that works. Open every important navigation link, press the primary buttons, submit the key forms, and follow the main user journey from start to finish. When one interaction fails, record the exact action where the expected result stops and test that path again after each correction.

Mobile layout is broken

1. Use the device toggle in the App Viewer toolbar to switch to mobile view.
2. Select the broken element in Design mode when available.
3. Describe the expected mobile layout and what must not change.
4. Apply one change, then verify desktop and mobile views plus loading, empty, hover, and error states.

Images or other assets are missing

1. Open the Files section and confirm that the referenced file exists.
2. Check that the path, file name, and format match the reference used by the app.
3. If the asset was recently moved or renamed, restore the reference or update it deliberately.
4. Select Reload App Viewer and test the affected page again.

The Agent changed the wrong element or broke another area

1. Open History and Remix from the last stable version.
2. Use Design mode to target the exact element when it is available.
3. State what must not change and make one change per prompt.
4. Verify the result before continuing to the next change.

Report an issue

Report the issue when Resolve is unavailable, the problem remains after a completed Resolve attempt, the Preview is unresponsive but Project chat still works, or unexpected behavior continues after the Agent investigates.

Open Feedback from Project chat

1. Open the affected Project chat and find the latest relevant Agent message.
2. Select ... (more options), then select Feedback.
3. In the support messenger, select Send us a message and send the report in the existing conversation when one already exists.

For the complete Issue Report flow, see Report an Issue.

Include enough detail to reproduce the problem

• Issue summary. Describe the problem in one or two sentences.
• Project or Chat Link. Include the URL where the problem occurred.
• Date and time. Include your time zone.
• Steps to reproduce. List the exact actions in order.
• Expected result and actual result. State what should have happened and what happened instead.
• What you already tried. Say whether Resolve appeared, what happened after it finished, and whether refreshing or Remix changed the result.
• Browser and device. Include the browser, operating system, and device type.
• Evidence. Attach a screenshot or recording and the relevant visible Issue Report or Console details.

Remove passwords, API keys, authentication tokens, cookies, payment details, and unrelated personal or confidential data before sharing screenshots or logs.

After the issue is fixed

Run the main user journey from start to finish. Check the Preview in both desktop and mobile views, open each page from the page selector, and confirm that the Console has no red error messages. If the app is ready to publish, replace any placeholder content and complete the publish checks in the App Viewer.

FAQ