Troubleshooting

This page helps you find the fix for the problems Reflex users meet most often.

Agents

The agent shows offline, or runs never start. Work through these checks in order:

1. Check that the agent process is running. In Docker, run docker compose logs agent.
2. If you registered the agent with a URL, the server must be able to reach it. The URL is opened from the server, not your browser. With the release Compose file use http://agent:7001, because localhost points at the server container. For systemd on one host use http://127.0.0.1:7001.
3. Check that the key in Reflex equals the agent’s AGENT_KEY. A mismatch looks like an offline agent.
4. If the agent was paired with a code, check that REFLEX_SERVER is the public HTTPS address of the server and that the agent’s data/ folder survives restarts.

There is no edit screen. Delete the agent and add it again. See Agents.

Setting AGENT_URL did not fix the connection. AGENT_URL is only the web UI origin (CORS). It is not the address you register. Remove it or set it to your Reflex URL.

I lost the admin password. The admin account is created only on the first start, so changing DEFAULT_PASSWORD later does nothing. Sign in as another administrator, or with single sign-on.

I lost the encryption key. Stored secrets cannot be recovered. Restore the key from your backup. Generate your own with java -jar reflex.jar --generate and back it up with the database. See Configuration.

Browsers and locators

“Element not found” right after opening a page. The page was not ready. Call wait() on the element before you click it. See Browser testing.

The element exists but cannot be found. It may be inside a shadow root. Use css=app-login >> shadow >> css=button#login, or >>> as a shortcut.

Locator errors at the start of a run. Every Lua project needs a locators.yaml in its root. Check that it exists and is valid YAML.

It works on my machine but fails on the agent. Check that the agent can download Chrome, or set AGENT_BROWSER_PATH and AGENT_CHROMEDRIVER_PATH. See Configuration. In FitNesse, run |script|browser download| in the suite setup.

I need to find a better selector. Open the page with the CLI and list its interactive elements:

reflex browser open <url>
reflex browser summary -i -c 25

For failures in a scheduled job, open the replay. To inspect a failing call, attach the live debugger.

Maven and Gitea access

Maven returns 401 or cannot find a Reflex artifact. The repository id in pom.xml and the server id in ~/.m2/settings.xml must both be gitea. Your token needs read access for packages. Use the release version without the v (tag v1.4.0 is 1.4.0). See Access, downloads and Maven.

Docker cannot pull the images. Log in with docker login git.bqa-solutions.nl using a Gitea token that can read packages.

Runs

A step in my Steps table never runs. Every step needs all six fields: name, description, condition, func, params and retry. A step with a missing field is skipped without an error. The name setup is reserved. See Scripts.

Files my script wrote are gone after the run. Each run uses a temporary workspace. Download the files from the run log, or store them in a system outside Reflex such as SFTP or a database.

FitNesse results do not reach the dashboard. Pass both -Dreflex.dashboard.url=ws://<host>:6001/run and -Dreflex.dashboard.suite=MySuite. Note ws:// and the /run path. See Dashboard.

Server and agent behave differently after an upgrade. Keep the server, agents, CLI and libraries on the same release version.

Still stuck?

Open an issue in the monorepo and attach the step log of the failing run.