AI app preview shows a blank screen: find the first failed runtime boundary

A worked example: where the task becomes difficult

A fictional imported repository includes a backend and a React client in separate folders. The preview runner starts at the root, where no browser app is served. Another project serves HTML but its script fails because an environment variable is missing. Both appear as blank frames. Treat them as different failures and record what the frame actually received before asking the agent to replace the application.

Decisions to make before implementation

Separate source hydration, dependency installation, process start, route readiness and browser rendering. Each stage needs an observable state and an error boundary. Check whether a preview URL is current or tied to an old runtime session. If the repository is a native server or command-line tool, explain that classification instead of inventing an unrelated web homepage to make the frame look successful.

A practical sequence for the work

Use the sequence below as a task boundary, not as a claim that the example has been executed. Work with approved inputs and the project’s actual architecture. If a required integration or permission is unavailable, keep that stage visibly incomplete rather than generating a plausible substitute result.

• Locate the actual application package and inspect its supported run command.
• Read runtime startup output and verify the preview route responds.
• Inspect the browser’s earliest failure after HTML and assets load.
• Fix the identified boundary and show progress or failure instead of indefinite preparation.

A detailed brief you can adapt for your agent

Replace the illustrative context with your approved facts and controlled inputs. Keep the stated boundaries when adapting the brief. The expected deliverable matters more than a particular tool name: ask for an explanation grounded in the inspected material and evidence for the requested outcome.

Diagnose this blank preview without replacing the project. Identify project type, app root, run command, runtime output and first browser error. Hydrate missing relevant source safely. Add observable startup stages and a bounded failure state. Report unsupported runtime requirements explicitly; do not create a placeholder website as proof of success.

Failure modes that an attractive preview can hide

A spinner that never stops can hide a failed installation or an unsupported project type. Add time-bounded readiness checks and show the stage that failed. Avoid automatic paid runtime provisioning without the intended authorization. If a static preview cannot execute the imported application, preserve code access and offer an accurate runtime option rather than claiming the app has loaded.

Technical references: Chrome: console features reference

Acceptance checks and the evidence to retain

Keep the project classification, resolved root, readiness evidence and first rendering result. Mark any runtime service that remains unavailable separately from the code edits.

Specific answers

Common questions