Guides
Troubleshooting
The questions that come up first, and what to check.
#The dashboard is empty
- The gateway must be started with
-api-url, and the key variable (defaultRAKUVO_API_KEY) must be set in the gateway's environment. The gateway refuses to start with-api-urland no key. - The key must be a gateway (or admin) key for the same organisation you are logged in to.
- Check the time range. A gateway that sent its last call two days ago shows nothing for "last hour".
- Metadata is sent in batches without blocking requests, so give it a moment after the first call.
#I changed a layer and nothing happened
- A gateway started with
-config-from-apipicks up changes on its next poll (-config-poll). The default is about 30 seconds. - A gateway started with the layer flags directly ignores the dashboard. Layer flags and
-config-from-apicannot be combined, so settings come from one place. - If a poll fails, the gateway keeps its last good configuration. Check that it can reach the control plane.
#A layer never shows any actions
Many layers act only when they have something to do.
- Prompt acts only on requests that offer tools, and in automatic mode only on models where it was measured to help.
- Loop guard acts only when an agent repeats itself. Zero is normal for a healthy agent.
- Tools acts only when a call is malformed or the judge vetoes one.
- Memory needs
-memory-dir, and an extraction model to write facts. Without a model it is read-only.
An empty list of notes on a run means the request went through untouched.
#Every call is "(unnamed)"
Send the X-Rakuvo-Agent header. See Naming your agents.
#"Forbidden" when I change a setting
The key has the viewer role. Use an admin key. See Keys and roles.
#Streaming looks slow
The gateway runs the layers on the complete response and then sends it as an event stream, so a streamed reply arrives after the model has finished instead of token by token. See How it works.
#The gateway will not start on 0.0.0.0
It refuses non-loopback addresses without authentication. Set -token-env to the name of an environment variable holding a bearer token.
#A webhook never arrives
It must be https and must not resolve to a private address. The request times out after a few seconds and is not guaranteed; check Alerts on the dashboard for the record that the rule fired.
#A layer made things worse on my agent
Turn it off and tell us. Gains depend on the model: a layer that fixes one failure does nothing for a model that does not have it. Use rakuvo bench to test a configuration on your own tasks before relying on it. See Terminal (CLI).