Troubleshooting

Catalyst Data: Troubleshooting and Recovery

Diagnose and recover common Catalyst Data failures without losing state.

ProductCatalyst DataVerified version1.11.0ComponentComparison Studio, Connectors, Datasets, Embeds, Entities, Evidence Ledger, Export Studio, Indicators, Institutional Access, Instruments, Observations, Persistent Workspaces, Public API, Quality Rules, Questions, Refresh Operations, Review and Revision, Saved Queries, Sources, Units and MethodsUpdatedJuly 17, 2026Reading time18 minutes
← Back to product guides

Catalyst Data · Troubleshooting

Governed entities, indicators, sources, evidence, questions, instruments, datasets, observations, quality, review, query, export, API, access, connectors, and refresh.

Audience: product users, administrators, reviewers, and integrators.

Last verified version: 1.11.0

Reading time: 18–30 minutes

Status: Published support documentation.

Purpose

This guide uses an evidence-first diagnostic sequence for Catalyst Data. Preserve state before changing configuration. Determine whether the failure comes from input data, permissions, version identity, browser assets, backend health, schema compatibility, external dependencies, or a product defect.

Prerequisites

  • Exact error message and time
  • Product, backend, package, and schema versions
  • Affected route, feature, record ID, and user role
  • A safe backup or export
  • The synthetic sample for a reference test

Sample data

This article uses a fictional Resilient Community Retrofit Program. The files contain one demonstration row for every documented feature, so each capability can be tested without private or production data.

Download CSV feature examples · Download JSON workspace example

Preview

# Feature Sample action Expected result Classification
1 Entities create the Community Center entity a stable entity ID synthetic-demo
2 Indicators define monthly electricity use with unit, method, and direction a reusable indicator definition synthetic-demo
3 Sources register utility data with publisher, URL, license, retrieval, and citation a provenance source record synthetic-demo
4 Evidence Ledger attach a bill and meter export to observations an evidence chain synthetic-demo
5 Questions state whether use fell after weather normalization a bounded analytical question synthetic-demo

The downloadable files include all 20 feature rows.

Procedure

  1. Stop repeated imports, submissions, migrations, or destructive retries.
  2. Record URL, feature, action, role, versions, browser/runtime, and expected result.
  3. Run the same feature row in a new synthetic workspace.
  4. If the sample fails, inspect health, logs, browser console, network response, and validation details.
  5. If the sample succeeds, compare real input schema, units, permissions, size, source, and status with the sample.
  6. Check version and schema identity before clearing caches or reinstalling.
  7. Apply the smallest reversible change.
  8. Repeat the sample and real workflow, then document the result.

Common problems

Symptom Likely cause Safe response
Observation rejected required field, type, unit, or relationship is invalid correct the record or schema
Comparison misleading definition, unit, period, or method differs use a crosswalk or mark non-comparable
Query empty filters exclude all reviewed records inspect status, period, product, and workspace
Refresh failed auth, schema, or source availability changed preserve prior snapshot and review exception

Escalation package

  • Product and version
  • Feature and component
  • Exact error text
  • Reproduction steps using synthetic data
  • Expected and actual result
  • Redacted log excerpt without secrets or personal data
  • Whether a clean sample reproduces the problem

Expected output

  • A reproducible diagnosis or bounded unresolved issue
  • Preserved user and system state
  • A documented workaround when available
  • A support-ready issue summary without private data

Verification

  • The synthetic feature succeeds after the fix.
  • The original workflow succeeds or remains safely isolated.
  • Version and health identity are consistent.
  • No duplicates, stale locks, or unintended cache artifacts remain.
  • The resolution is reflected in a support article, known issue, or release record when appropriate.

Responsible use

Governed data is not automatically true or fit for every purpose; preserve source rights, privacy, definitions, uncertainty, and review.

Never place credentials, API keys, private URLs, personal records, client documents, or confidential logs in a public article or issue.

Scroll to Top