Skip to content

estuary/agent-skills / skills/estuary-catalog-status

estuary-catalog-status

Verified

Run flowctl catalog status to check the control-plane state of an Estuary resource, or list catalog specs to see which connectors exist and which are active. Use when checking whether a task is running, disabled, or failing, interpreting status output, or enumerating connectors. Use when user says "check task status", "is my capture running", "catalog status", "flowctl catalog status", "what's wrong with my capture", "task failing", "check catalog status", "collection status", "derivation status", "why is my task disabled", "list my connectors", "show me my connectors", "list captures", "list materializations", "what connectors do I have", or "show me all my active connectors".

flowctl catalog status - Check status of Estuary resources

Concepts: The catalog contains all Estuary specs — captures, materializations, collections, derivations, and tests. The status command shows the current control-plane state including whether the task is running, its last failure, publication history, and shard health.

Note: This command shows control-plane status — whether the controller has activated the task, published specs, and received shard health reports. It does not directly poll data-plane (runtime) state in real time, so brief transient failures or throughput issues may not be reflected here. For real-time runtime behavior, use flowctl logs.

Prerequisites

flowctl auth login

Basic Usage

flowctl catalog status <task> --output json | jq

Check a task and everything connected to it (upstream/downstream collections and tasks):

flowctl catalog status <task> --connected --output json | jq

Listing connectors

catalog status targets a single named resource. To enumerate which connectors exist — e.g. "show me all my active connectors" — use flowctl catalog list instead.

Gotcha — the type flags are mutually exclusive. --captures, --materializations, --collections, and --tests are include filters and only one may be passed at a time. Combining them fails:

$ flowctl catalog list --captures --materializations
error: the argument '--captures' cannot be used with '--materializations'

The --captures=false negative form shown in --help is not accepted by the CLI (error: unexpected value 'false'), so you cannot exclude types that way either.

To get captures and materializations together, run catalog list with no type flags (which returns everything) and filter by type in jq:

# All ACTIVE (non-disabled) connectors — captures + materializations — in one call
flowctl catalog list -o json | jq -r '
  select((.liveSpec.catalogType == "capture" or .liveSpec.catalogType == "materialization")
         and .liveSpec.isDisabled != true)
  | .catalogName + "  [" + .liveSpec.catalogType + "]  [" + (.status.type // "?") + "]"'

Or just run two separate commands — flowctl catalog list --captures -o json and flowctl catalog list --materializations -o json.

Key points when parsing the output:

  • Output is line-delimited JSON (one object per line), not a JSON array. Pipe to jq without .[] — each line is already a single object. Wrapping with .[] fails with Cannot index string with string "...".
  • catalogType and isDisabled live under .liveSpec (not at the top level — that top-level .catalogType only exists on catalog status output).
  • Filter active vs. disabled with select(.liveSpec.isDisabled != true); drop it to include TASK_DISABLED specs.
  • --prefix <tenant>/ narrows the list to one tenant; --name <spec> selects exact specs (repeatable).

Interpreting Status

Status Types

status.typestatus.summaryWhat it means
OKRunningTask is healthy and processing data
OKOkCollection is healthy (collections show Ok not Running)
WARNINGvariesTask is running but has recent failures or is retrying
TASK_DISABLEDTask shards are disabledTask has been intentionally paused
ERRORerror messageTask has failed repeatedly and is not recovering

Key Output Fields

# Quick health check — just the essentials
flowctl catalog status <task> -o json | jq '{
  status:             .status.type,
  summary:            .status.summary,
  recent_failures:    .status.controller.activation.recentFailureCount,
  last_failure_error: (.status.controller.activation.lastFailure.fields.error // .status.controller.activation.lastFailure.message // null)
}'

Note: Use .fields.error rather than the full .lastFailure object — for schema validation failures, the full object includes the entire failing document and produces walls of JSON.

FieldWhat it tells you
.status.typeOverall health: OK, WARNING, TASK_DISABLED, ERROR
.status.summaryHuman-readable status message
.status.controller.failuresCumulative controller failure count
.status.controller.activation.shardStatus.statusShard-level health (OK or degraded)
.status.controller.activation.shardStatus.countNumber of status reports from shards
.status.controller.activation.recentFailureCountRecent shard failures (resets on recovery)
.status.controller.activation.lastFailureLast failure details: timestamp, message, and error
.status.controller.publications.historyRecent publication events with results
.status.controller.nextRunWhen the controller will next check the task
.liveSpecUpdatedAtWhen the spec was last published
.userCapabilityYour permission level (admin, write, read)

Common jq Recipes

# Get the last failure message and timestamp
flowctl catalog status <task> -o json | jq '{
  ts: .status.controller.activation.lastFailure.ts,
  message: .status.controller.activation.lastFailure.message,
  error: .status.controller.activation.lastFailure.fields.error
}'

# Check when the spec was last published
flowctl catalog status <task> -o json | jq '.liveSpecUpdatedAt'

# Get publication history
flowctl catalog status <task> -o json | jq '.status.controller.publications.history[] | {id, created, detail, result: .result.type}'

# Check all connected resources at a glance
flowctl catalog status <task> --connected -o json | jq -c '{name: .catalogName, type: .catalogType, status: .status.type, summary: .status.summary}'

Troubleshooting by Status

Task shows WARNING

The task is running but has recent issues. Check:

# What failed recently?
flowctl catalog status <task> -o json | jq '.status.controller.activation.lastFailure'

If failures are intermittent and recentFailureCount is low, the task is likely self-recovering. If failures are climbing, check logs with flowctl logs --task <task> --since 1d.

Task shows TASK_DISABLED

The task was intentionally paused (shards disabled). Re-enable it in the Estuary web app (edit the task and click Save and Publish), or use the estuary-connector-restart skill to re-enable via flowctl.

Task shows ERROR

The task has failed and is not recovering. Steps:

  1. Get the error: flowctl catalog status <task> -o json | jq '.status.controller.activation.lastFailure.fields.error' — this may be truncated in the status output. If the message ends with [truncated], use flowctl logs (step 2) for the full error.
  2. Check logs: flowctl logs --task <task> --since 1d
  3. If the error is a configuration issue, fix and re-publish
  4. If recovery logs are corrupted, the task may need to be deleted and recreated — this can cause data loss. Recommend the user contact Estuary support before proceeding (Slack: https://go.estuary.dev/slack or email: support@estuary.dev) and include the task name, the error message, and what they've tried so far.

Status not updating after publish

The controller runs on a schedule. Check when the next run is:

flowctl catalog status <task> -o json | jq '.status.controller.nextRun'

After a publish, the controller typically picks up changes within a few minutes.

Related Skills

  • estuary-task-health — Single-task health check combining status, data flow, logs, and history
  • estuary-task-stats — Check whether data is actually flowing through the task
  • estuary-catalog-history — View publication history and recent spec changes
  • estuary-logs — Search and filter task logs for detailed runtime information
  • estuary-connector-restart — If the task needs to be paused and restarted via flowctl
  • estuary-ssh-tunnels — If the failure involves SSH tunnel or network connectivity issues

Tips

  • Always use -o json | jq for structured output — table mode omits many fields
  • --connected is useful for checking an entire pipeline's health at once
  • recentFailureCount > 0 with status.type: OK means the task recovered on its own
  • .status.controller.activation.lastFailure persists even after recovery — it shows the most recent failure, not necessarily a current one
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall