Troubleshooting

Environment unreachable

Symptoms:

• the session browser shows a connection error
• runs fail quickly with navigation failures

Checklist:

• confirm the environment Base URL is correct (including https://)
• confirm the URL is reachable from the public internet (agent sessions run remotely)
• avoid localhost and 127.0.0.1 (those refer to the agent container, not your machine)

Agent gets stuck or loops

This usually means the instructions are ambiguous or the UI state is unexpected.

Fixes:

• watch the session live to see what the agent is reacting to
• add constraints: "If a modal appears, close it", "Wait for the dashboard table to appear"
• split long tests into smaller checks

Flaky tests

Common causes:

• async loading or race conditions
• dynamic content (randomized lists, changing IDs)
• shared test data in a shared staging environment

Fixes:

• verify structure (counts, presence) rather than exact values where data is dynamic
• use stable seed data and dedicated test accounts
• quarantine unstable tests until you can make them deterministic

Runs pending for a long time

Runs can wait for capacity. If a run is pending longer than expected:

• check for other active runs in the same environment
• reduce suite size or concurrency by splitting into multiple processes
• consider upgrading capacity if this happens frequently