How do I install the Estuary Connector Restart skill?

Run npx skillmds@latest add estuary/estuary-connector-restart in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Estuary Connector Restart safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Estuary Connector Restart?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Estuary Connector Restart free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Estuary Connector Restart?

estuary (@estuary) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Estuary Connector Restart by estuary

Name: Estuary Connector Restart
Author: estuary

Estuary Connector Restart

Pause and restart Estuary connectors by disabling and re-enabling shards via flowctl. Use when temporarily stopping a connector, performing source/destination maintenance, or forcing a fresh restart to clear transient errors or load updated configs immediately. Use when user says "pause connector", "stop connector", "restart connector", "disable connector", "enable connector", "re-enable task", "disable shards", "stop my capture", "stop my materialization", "disable my materialization", "force restart connector", "connector maintenance", "temporarily stop processing", "shards disable true", "enable shards", "resume connector", or "unpause connector".

estuary Updated Sep 17, 2026

File contents

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:

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

---name: estuary-connector-restartdescription: Pause and restart Estuary connectors by disabling and re-enabling shards via flowctl. Use when temporarily stopping a connector, performing source/destination maintenance, or forcing a fresh restart to clear transient errors or load updated configs immediately. Use when user says "pause connector", "stop connector", "restart connector", "disable connector", "enable connector", "re-enable task", "disable shards", "stop my capture", "stop my materialization", "disable my materialization", "force restart connector", "connector maintenance", "temporarily stop processing", "shards disable true", "enable shards", "resume connector", or "unpause connector".---# Restart a Connector — Disable and Re-enable via flowctlTemporarily 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```bashflowctl auth login```## Step 1: Pull the current spec```bashflowctl catalog pull-specs --name <task-name>```This creates a `flow.yaml` and a directory with the task's YAML spec.## Step 2: Disable the connectorEdit the task's YAML file (under `<task-name>/flow.yaml`) and add a `shards` block at the same level as `endpoint` and `bindings`:```yamlcaptures: 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:```bashflowctl catalog publish --source flow.yaml --auto-approve```Confirm it's disabled:```bashflowctl catalog status <task-name> --output json | jq '.status.type'# Expected: "TASK_DISABLED"```## Step 3: Re-enable the connectorEdit 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 errorsPublish again:```bashflowctl catalog publish --source flow.yaml --auto-approve```Verify it's running:```bashflowctl 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

Frequently asked questions