Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
BlueprintPersistenceError is a structured diagnostic sink for failures that occur during blueprint run persistence — replacing silent logger.error catches in BlueprintStorageService.persistStep and the runInBackground helper. Each row records the phase of the blueprint pipeline that failed, the associated run ID, the workspace context (nullable for pre-auth failures), and the full error detail including message, type, stack, and an arbitrary JSON payload. Rows are pruned opportunistically after 30 days (~1-in-20 writes trigger cleanup), mirroring the connector_sync_diagnostics retention pattern. The entity is append-only and owned entirely by the system — no user-facing PATCH route exists.
| Naming | Value |
|---|
| Object | BlueprintPersistenceError |
Resource type (JSON:API type) | blueprint_persistence_error |
| Collection / records root | — (not a records root) |
| REST base | /v1/blueprint-persistence-errors |
| Entity class | BlueprintPersistenceError |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/blueprint-persistence-errors | 🟡 Planned |
| Retrieve | GET /v1/blueprint-persistence-errors/{id} | 🟡 Planned |
| Create | POST /v1/blueprint-persistence-errors | 🟡 Planned |
| Update | PATCH /v1/blueprint-persistence-errors/{id} | 🟡 Planned |
| Delete | DELETE /v1/blueprint-persistence-errors/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| error_id | 🔒 system — UUID | ✅ Yes | unique, NOT NULL, default gen_random_uuid() | — | Public-facing unique identifier for this error row. Generated by the database via gen_random_uuid() at insert time. Used as the JSON:API id. |
| blueprint_run_id | string (text) | ✅ Yes | NOT NULL | — | Identifies the blueprint run that triggered this failure. Stored as free-form text matching the run’s external identifier. Indexed for efficient per-run lookup. |
| phase | enum (blueprint_persistence_error_phase_enum) | ✅ Yes | NOT NULL; native Postgres enum stored as enum value string | upsert_run | increment_step | create_step | upload_screenshot | update_run_terminal | persist_step | background_runner | handler | The pipeline phase in which the error occurred. Backed by a native Postgres enum. Indexed alongside created_at for time-bucketed phase analysis. |
| error_type | string (text) | ⚪ No | nullable | — | Optional classification of the error class or exception type (e.g. the JavaScript error constructor name). Null when not captured. |
| error_message | string (text) | ✅ Yes | NOT NULL | — | The full human-readable error message from the caught exception. |
| stack | string (text) | ⚪ No | nullable | — | Full exception stack trace at the point of capture. Null when unavailable (e.g. non-Error throws). |
| payload | jsonb | ⚪ No | nullable, JSONB | — | Arbitrary structured context captured at the failure site — may include step index, run ID, workspace ID, or any other diagnostic fields relevant to the phase. Shape varies per phase. |
| created_at | 🔒 system — timestamptz | ✅ Yes | NOT NULL, default now() | — | Timestamp set by the MikroORM onCreate hook (and defaulted to now() at the database level) when the error row is inserted. No updated_at — this entity is append-only. |
| deleted_at | 🔒 system — timestamptz | ⚪ No | nullable | — | Soft-delete timestamp. Set by the application retention logic (BlueprintPersistenceErrorService.write prunes rows older than 30 days on ~1/20 writes). Null means the row is active. Rows with deleted_at set are filtered from normal queries. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | ⚪ No | The workspace this error belongs to. Nullable because some blueprint failure modes are caught before auth resolves a workspace (e.g. handler-level catch on a malformed request). Rows where workspace is null are intentionally invisible to the tenant user role in Hasura — only accessible via admin / Metabase / direct DB queries. References core_api.workspaces. |
System-computed
- error_id: generated by gen_random_uuid() at the database level on insert; never supplied by callers
- created_at: set by MikroORM onCreate hook (also defaulted to now() in the DDL); no updated_at column exists — the entity is append-only
- deleted_at: managed by application-level retention logic inside BlueprintPersistenceErrorService.write(), which prunes rows older than 30 days on approximately 1-in-20 writes; no scheduled job is required
- Retention sampling: the ~1/20 probabilistic pruning is designed to avoid a dedicated cron; the window may allow rows to survive slightly beyond 30 days
- Workspace nullability: workspace_pk is nullable by design to capture pre-auth failures; Hasura user-role select_permissions filter by workspace.workspace_id, making null-workspace rows admin-only
Example
{
"data": {
"type": "blueprint_persistence_error",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"error_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"blueprint_run_id": "run_01HXYZ9876ABCDEF",
"phase": "persist_step",
"error_type": "EntityNotFoundError",
"error_message": "Could not find BlueprintRun with id run_01HXYZ9876ABCDEF",
"stack": "Error: Could not find BlueprintRun with id run_01HXYZ9876ABCDEF\n at BlueprintStorageService.persistStep (/app/src/services/blueprint-storage.service.ts:142:13)",
"payload": {
"step_index": 3,
"run_id": "run_01HXYZ9876ABCDEF",
"workspace_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
},
"created_at": "2026-04-29T14:23:11.000Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
}
}
}
}
apps/api/src/database/entities/BlueprintPersistenceError.ts · domain: automation · tier: Activity
