Agent UI Troubleshooting

Agent UI problems usually come from project structure, dev server startup, port conflicts, or remote sync.

Preview Stuck Loading

Check the UI project:

ls
cat package.json

The project should have either:

• package.json with a dev or start script.
• index.html for a static UI.

If it is a React/Vite/Next app, make sure the dev server respects PORT.

Blank Preview

Open the dev server URL directly in a browser.

If the page is blank there too, the problem is inside the UI app. Check the console and dev server logs.

Remote UI Problems

On a remote engine:

• The dev server must bind to 0.0.0.0.
• The port must be reachable from xCloud.
• Dependencies may need time to install.
• Large UIs can take time to sync.

Run Settings > Engine > Repair / update remote helper if remote UI actions stop working.

Runtime Bridge Missing

If window.xcloud is undefined:

1. Restart the preview.
2. Confirm xcloud-runtime.js exists in the UI project.
3. Confirm the project was opened through xCloud preview.
4. For custom frameworks, import or include the runtime manually.

UI Tools Do Not Run

UI tools only work while the preview is open and the tool is registered.

Check:

• The UI calls window.xcloud.agent.registerTool.
• Tool name matches what the agent calls.
• The preview iframe is loaded.
• The tool returns JSON-serializable data.

Imported Agent UI Missing

If an imported agent appears but its UI does not:

1. Confirm the package included a ui/ folder.
2. Open the agent workspace and check ui-config.json.
3. Reconnect the UI folder from the preview panel.
4. If remote, wait for upload/extract to finish.