> ## 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.
# CollectError
> CollectError is a structured diagnostic sink for runtime errors raised by the Chrome extension while executing a saved blueprint (auth walls, page-not-found, ti
CollectError is a structured diagnostic sink for runtime errors raised by the Chrome extension while executing a saved blueprint (auth walls, page-not-found, timeouts, selector failures, etc.). Each row captures the provider, error classification, severity, and optional contextual metadata at the moment the failure occurred. Rows are created exclusively by `CollectErrorService.write()` via `POST /v1/collect/blueprint-error`; the same service also opens a GitHub issue for human triage. Rows are soft-deleted and pruned opportunistically (sampled \~1 in 20 writes) after 30 days. The entity belongs to a nullable Workspace and optionally references the parent Collect session that triggered the error.
| Naming | Value |
| ------------------------------- | --------------------------------- |
| Object | CollectError |
| Resource type (JSON:API `type`) | `collect_error` |
| Collection / records root | โ (not a records root) |
| REST base | `/v1/collect-errors` |
| Entity class | `CollectError` |
**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/collect-errors` | ๐ก Planned |
| Retrieve | `GET /v1/collect-errors/{id}` | ๐ก Planned |
| Create | `POST /v1/collect-errors` | ๐ก Planned |
| Update | `PATCH /v1/collect-errors/{id}` | ๐ก Planned |
| Delete | `DELETE /v1/collect-errors/{id}` | ๐ก Planned |
## Data model
### Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
| ------------------ | ------------------------------------- | -------- | -------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| error\_id | string (UUID) โ ๐ system | โ
Yes | unique; default gen\_random\_uuid() | โ | Stable public identifier for this error record. Generated by the database at insert time. Used as the JSON:API `id`. |
| provider | string (text) | โ
Yes | not null | โ | Slug identifying the web provider the blueprint was targeting when the error occurred (e.g. `linkedin`, `hubspot`, `salesforce`). Free-form text; set by the Chrome extension. |
| error\_type | string (text) | โ
Yes | not null | โ | Short machine-readable classification of the failure class (e.g. `auth_wall`, `selector_not_found`, `page_timeout`, `unexpected_redirect`). Indexed alongside `created_at` for Metabase aggregations. |
| error\_message | string (text) | โ
Yes | not null | โ | Human-readable description of what went wrong, as reported by the Chrome extension at the point of failure. |
| severity | enum (collect\_error\_severity\_enum) | โ
Yes | not null; stored as native PostgreSQL enum in core\_api schema | low \| medium \| high \| critical | Operational severity of the error. Determined by the Chrome extension or CollectErrorService based on whether the error is recoverable and how much of the blueprint it blocks. |
| metadata | jsonb | โช No | nullable | โ | Arbitrary structured context attached by the Chrome extension at the time of the error โ may include DOM selector paths, step indexes, blueprint version, partial extraction results, or browser state. Schema is free-form. |
| source\_url | string (text) | โช No | nullable | โ | The full URL the Chrome extension was visiting when the error was raised. |
| domain | string (text) | โช No | nullable | โ | Extracted domain of `source_url` (e.g. `linkedin.com`). Stored separately for indexed lookups without requiring URL parsing at query time. |
| github\_issue\_url | string (text) | โช No | nullable | โ | URL of the GitHub issue automatically created for human triage by `CollectErrorService.write()` in parallel with this row insert. Preserves the prior error-handling path (GitHub issue creation) alongside the new structured row. |
| occurred\_at | timestamptz | โช No | nullable | โ | Client-reported timestamp of when the error actually occurred in the browser, as opposed to `created_at` which is the server ingestion time. May differ from `created_at` by network/queue latency. |
| created\_at | timestamptz โ ๐ system | โ
Yes | not null; default now(); set via MikroORM onCreate hook | โ | Server-side ingestion timestamp. Set automatically on insert; never modified after. |
| deleted\_at | timestamptz โ ๐ system | โช No | nullable; soft-delete sentinel | โ | Soft-delete timestamp. Null means the row is active. Set by `CollectErrorService` during opportunistic 30-day pruning (sampled \~1/20 writes). Rows with `deleted_at IS NOT NULL` are excluded from standard queries and are tenant-invisible via Hasura RLS. |
### Relationships
| Name | Type | Required | Description |
| --------- | ------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspace | to-one (ManyToOne) | No โ nullable | The Workspace this error belongs to. Stored as `workspace_pk` (FK โ `core_api.workspaces.pk`, ON DELETE CASCADE). Nullable by design: errors with `workspace_pk IS NULL` are tenant-invisible via Hasura RLS and are only accessible via admin/direct DB access. This mirrors the `BlueprintPersistenceError.workspace` pattern. |
| collect | to-one (ManyToOne) | No โ nullable | The parent Collect session (Chrome extension execution run) during which this error was raised. Stored as `collect_pk` (FK โ `core_api.collects.pk`, ON DELETE SET NULL). Nullable because errors may be reported outside of a tracked Collect session, and the parent session can be deleted independently without cascading the error row. |
### System-computed
* error\_id โ generated by gen\_random\_uuid() at INSERT time; never modified
* created\_at โ set via MikroORM onCreate hook (new Date()) on INSERT; no updatedAt hook on this entity
* deleted\_at โ managed by CollectErrorService opportunistic pruning (\~1/20 writes prune rows older than 30 days via soft-delete); not set by standard MikroORM lifecycle hooks
* workspace\_pk โ FK resolved from request context by CollectErrorService.write(); the caller supplies the Workspace entity reference, not a raw ID
* collect\_pk โ FK resolved from the paired Collect session if one is active; NULL when the error arrives without a session context
## Example
```json theme={null}
{
"data": {
"type": "collect_error",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"attributes": {
"provider": "linkedin",
"error_type": "auth_wall",
"error_message": "Login gate detected at /in/johndoe โ blueprint paused.",
"severity": "high",
"metadata": {
"selector": "#main-content",
"step_index": 3,
"blueprint_version": "2"
},
"source_url": "https://www.linkedin.com/in/johndoe",
"domain": "linkedin.com",
"github_issue_url": "https://github.com/well-app/ops/issues/4821",
"occurred_at": "2026-04-30T14:22:10.000Z",
"created_at": "2026-04-30T14:22:11.543Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "ws-uuid-here" }
},
"collect": {
"data": { "type": "collect", "id": "collect-uuid-here" }
}
}
}
}
```
Source: `/Users/maximechampoux/platform/apps/api/src/database/entities/CollectError.ts` ยท domain: ingestion ยท tier: Infrastructure