CollectError - Well Starter Kit

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

{
  "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}

Documentation Index

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example