RumataAgent troubleshooting
Exact symptoms agents hit on Rumata, what causes them, and the fix, across backends, frontends, data, files, workflows and AI.
Step-by-step guidance.
Before you start
- The failing response, log or run trace.
Diagnose before changing
Read the real evidence first: build logs for that build ID, node input and output in the run trace, or the response body. Change one cause at a time. Never retry a failed build or paid generation unchanged.
Backends and builds
| Symptom | Cause | Fix |
|---|---|---|
| Empty service list | No service registered yet | Create one. Hosting is available. |
| Backend changes do not register | Only local manifests were edited | Call `configureBackendService`. |
| Update rejected for revision | Stale `expectedRevision` | Read `getBackendService` and retry with the current revision. |
| Development port conflict | Assumed 8081, or used a reserved port | Pick a free port through `listen(0)`. Ports 3001, 4096, 5173 and 8080 are reserved. |
| Service will not answer | Bound to localhost or a fixed port | Listen on `0.0.0.0` and the injected `PORT`. |
| Database never sleeps | `/health` runs SQL or `SELECT 1` | Check only the HTTP process in `/health`. |
| Gateway health returns 503 while asleep | Expected while sleeping | Test wake-up with a real application operation. |
| Build works locally, fails remotely | Uncommitted files, or needs `.git` | Reproduce from `git archive HEAD`. See Deployment. |
| 403 from a raw preview request | Preview needs Studio authorization | Use `debugBackendRequest` or the browser. Do not publish to bypass it. |
| Public 404 from a deployed backend | Access grant or publication | Inspect Manage access. Do not switch to `direct` or embed platform credentials. |
Frontends
| Symptom | Cause | Fix |
|---|---|---|
| `new URL` throws in preview | Relative binding base | Join strings. See Frontend. |
| API path loses the service ID | Base without trailing slash passed to `new URL` | Join strings. |
| Bodyless DELETE returns 400 | `content-type: application/json` with no body | Send that header only with a body. |
| Workflow client cannot reach the backend | It only routes workflows | Use the `VITE_*` binding. |
| Dialog controls sit behind a map | Map panes share the stacking context | Set `isolation: isolate` on the map wrapper. |
| Browser reports `Failed to fetch` | Often a server error, not CORS | Inspect activity traces or the backend response first. |
Database and files
| Symptom | Cause | Fix |
|---|---|---|
| `CREATE EXTENSION` fails | Rumata installs extensions | Use `setDatabaseExtension`, then poll `listDatabaseExtensions` until `applied`. |
| INSERT becomes `DEFAULT VALUES` | A placeholder was dropped | List every required column, and treat a constraint error as incomplete input. |
| Pooler rejects `statement_timeout` | Sent in the startup packet | Set `query_timeout` on the client. |
| Storage rejects `photo..png` | `..` is rejected anywhere | Validate names before building the path; return 400. |
| HTTP 200 but a file failed to sign | Per-file errors | Read each `results` entry. |
| SVG downloads instead of displaying | Active content is stored as an attachment | Use raster formats for inline display. |
| Double `/api` in storage URLs | `storageApiBaseUrl` already has the prefix | Do not append it. |
| First gallery page fails | GET prefix bound as `{{prefix}}` | Bind `{{queryParams.prefix}}`, and allow empty `queryParams`. |
Workflows and AI
| Symptom | Cause | Fix |
|---|---|---|
| Graph rejected on port kind | `error` used as a kind | Kind is `data` or `control`. `error` is a port ID. |
| Merge never finishes | It waits for every port, including skipped branches | Finish branches separately or call a shared workflow. |
| Publishing rejects a loop body | Nested loop, AI node or signal wait in the body | Move it to a called workflow. |
| Key cannot run the workflow | It is a draft, or a custom group lacks the grant | Publish with `publishIntegrationWorkflow`; grant 136 to custom groups. |
| HTTP 200 but no result | Run is still pending | Treat `queued`, `running` and `waiting` as pending. Use `waitForSuccess`. |
| Schedule is not firing | Saved graph only | Require `schedule.synced`, then verify `getWorkflowSchedule` has `nextRun`. Retry `syncWorkflowSchedule`. |
| Connector call has no credentials | No bound connection | Bind a connection with `listSecrets.secretId`, then refresh `listConnectors`. |
| Model ignores an image | URL only appears in text | Pass `config.images` and use a vision-capable model. |
| Agent says it saved but nothing changed | Tool not called, or it hid zero rows | Inspect `toolCalls` and `childRunId`. Tools must report no-change outcomes. |