Estuary Connector Restart

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 

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 /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  --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  --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 /

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 --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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: estuary
• Source: estuary/agent-skills
• License: Apache-2.0
• Homepage: https://estuary.dev

Install and usage instructions live in the source repository linked above.