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 (default RAKUVO_API_KEY) must be set in the gateway's environment. The gateway refuses to start with -api-url and 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-api picks 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-api cannot 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).