Restart a Connector — Disable and Re-enable via flowctl

Temporarily pause a capture or materialization by disabling its shards, then re-enable it. The connector resumes from its last checkpoint — no data is lost. Works for both captures and materializations.

Prerequisites

flowctl auth login

Step 1: Pull the current spec

flowctl catalog pull-specs --name <task-name>

This creates a flow.yaml and a directory with the task's YAML spec.

Step 2: Disable the connector

Edit the task's YAML file (under <task-name>/flow.yaml) and add a shards block at the same level as endpoint and bindings:

captures:
  acmeCo/source-postgres:
    endpoint:
      connector:
        image: ghcr.io/estuary/source-postgres:v1
        config: ...
    bindings:
      - resource: ...
        target: ...
    # Add this block to disable:
    shards:
      disable: true
    # To re-enable: remove the shards block and any expectPubId line

If a shards section already exists, just add disable: true to it.

Publish to apply:

flowctl catalog publish --source flow.yaml --auto-approve

Confirm it's disabled:

flowctl catalog status <task-name> --output json | jq '.status.type'
# Expected: "TASK_DISABLED"

Step 3: Re-enable the connector

Edit the same file and:

1. Remove disable: true (or the entire shards block if it only contained that) — do not set it to false (an explicit false is treated as a setting and may cause unexpected behavior)
2. Remove the expectPubId line if present — it's stale after the disable publish and will cause errors

Publish again:

flowctl catalog publish --source flow.yaml --auto-approve

Verify it's running:

flowctl catalog status <task-name> --output json | jq '.status.type'
# Expected: "WARNING" initially (shards starting), then "OK" after 30-120 seconds

Activation timing varies: small connectors take 30-60 seconds, large connectors (100+ bindings) take 60-120 seconds.

Optionally remove the pulled spec files when done: rm -rf flow.yaml <tenant>/

Troubleshooting

Problem	Solution
expected publication ID ... was not matched	Remove the expectPubId line from the spec and re-publish
Status stuck on WARNING after re-enable	Wait 30-120 seconds. If it persists, check logs with flowctl logs --task <task-name> --since 1h
dns error: failed to lookup address	Transient — retry the publish command
Status still OK right after disable	Wait a few seconds and re-check — status updates may take a moment
Can't re-enable	Ensure you removed disable: true entirely (not set to false), removed the empty shards block, and removed expectPubId

Tips

• Disabling is safer than deleting — all configuration and state are preserved
• The connector resumes from its checkpoint when re-enabled
• To force an immediate restart when a connector is in retry backoff (up to 15 min between retries), a disable/enable cycle bypasses the backoff entirely

Related Skills

• estuary-flowctl-setup — Install and authenticate flowctl before using this skill
• estuary-catalog-status — Check task health before and after restarting
• estuary-logs — Investigate errors if the connector doesn't recover after restart