Troubleshooting
Use this guide to resolve common Oruoma workspace, workflow, SDK, and API issues.
Authentication and workspace access
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized | Missing, expired, or wrong workspace API key | Create a scoped workspace API key and send it as Authorization: Bearer <key>. |
403 Forbidden | Account role cannot perform the action | Use an account with the smallest role that includes the needed permission. |
404 Not Found for a workspace route | Wrong workspace id or no membership in that workspace | Confirm the URL uses /api/ws/{workspace_id}/... and that the account belongs to the workspace. |
| Secret value is not visible after creation | Expected behavior | Secret APIs return metadata only. Store the value in your own secret manager before writing it. |
Jobs and tasks
| Symptom | Likely cause | Fix |
|---|---|---|
| A task appears stale | The worker or agent stopped renewing the task lease | Resume the task, update current_step, and renew the lease while work continues. |
| Work says completed but users cannot see results | The job/task was completed without a human-readable report | Add a summary report and update the task/job with the final outcome. |
| Task notes feel noisy | Notes repeat old information | Add only new facts, decisions, blockers, or verification evidence. |
| Deliverable gate blocks workflow progress | Required deliverable is missing or incomplete | Open the run step, complete the required deliverable, then retry/reconcile the run. |
Workflows
| Symptom | Likely cause | Fix |
|---|---|---|
| Workflow will not start | Invalid graph or missing start node | Validate that the graph has one start path and every node has required data. |
| Switch goes down the wrong branch | Expression does not match produced output | Confirm the expression references the actual run input or deliverable key. |
| Cancelled run keeps visible step jobs | Step jobs were already created before cancellation | Cancel the run; then inspect child jobs and cancel any still-running work that is no longer needed. |
| Approval step does not continue | Approval deliverable is not marked complete | Complete the approval deliverable with a clear decision value. |
SDK and API usage
When debugging payload shape or route usage, compare against working SDK examples and the full SDK examples table.
| Symptom | Likely cause | Fix |
|---|---|---|
| SDK cannot find a route | Base URL or workspace id is wrong | Use the Oruoma base URL and pass the workspace id separately when the SDK expects it. |
| API returns validation errors | Payload shape does not match the endpoint | Compare the request with the API reference and prefer SDK helpers for common flows. |
| Duplicate records appear | Client retried a create request without an idempotency key | Use an idempotency key where supported, or check for an existing resource before retrying. |
| Secret reference fails | Secret name is absent or misspelled | Create the secret with the exact uppercase name referenced by ${secret.NAME}. |
When to escalate
Escalate to your Oruoma engineering contact when:
- A workspace route returns a server error after retrying with a valid request.
- A workflow run is stuck after all required deliverables are complete.
Include the workspace id, job/run id, timestamp, request id if available, and the smallest payload that reproduces the issue. Do not include secrets or tokens.