That error usually means your ECS work pool’s base job template and the prefect-aws package in your worker environment are out of sync. In Prefect 3.x, ECS pull workers do expect a

cluster

variable, but if your worker upgraded/downgraded (or the template drifted), the model can reject

cluster

with “Got unexpected keyword argument ‘cluster’”. Quick checks and fixes 1) Inspect your work pool to see what variables it currently expects

prefect work-pool inspect "<your-ecs-pool>"

Look for the

base_job_template.variables.properties

. If

cluster

is missing or the schema looks different from what you expect, your template is stale for the version of prefect-aws on your worker. 2) Get the current default ECS template and update your pool

prefect work-pool get-default-base-job-template --type ecs > ecs.json
prefect work-pool update "<your-ecs-pool>" --base-job-template ecs.json

This refreshes the pool’s template to match your installed version. You can re-apply any customizations after. 3) Make sure your worker and deployment environments use compatible versions - Pin the packages in the worker container/venv:

pip install -U "prefect>=3,<4" "prefect-aws>=0.5,<2"  # example pins; align both together

A mismatch between

prefect

and

prefect-aws

is the most common cause of this error. 4) Verify that you set

cluster

in job variables (deployment or pool) -

cluster

should be a cluster name or ARN (e.g.,

my-ecs-cluster

or its ARN). - Minimal example of deployment job variables:

job_variables:
  cluster: "my-ecs-cluster"
  task_definition_arn: "arn:aws:ecs:...:task-definition/my-task:42"

These keys are templated into the ECS request. The default ECS template includes

task_run_request.cluster

which uses this

cluster

value. Helpful commands (verified) - View the default ECS base job template:

prefect work-pool get-default-base-job-template --type ecs

- Inspect a work pool:

prefect work-pool inspect "<your-ecs-pool>"

- Update a work pool’s base job template:

prefect work-pool update "<your-ecs-pool>" --base-job-template ecs.json

Docs - ECS guide: Prefect AWS ECS guide - Customize job variables: Customize job variables - Manage work pools: Manage work pools If you can share: - The exact

prefect

and

prefect-aws

versions in your worker container - The stack trace (top ~30 lines) - Whether

cluster

is set in your deployment’s

job_variables

or only in the work pool …I can pinpoint whether this is a version mismatch or a template drift and suggest the precise fix.

Got it — if the CLI shows the same as the UI, let’s switch to checks that will pinpoint why the worker is rejecting

cluster

. Most likely cause: a version mismatch between your worker’s

prefect-aws

and the work pool’s base job template. If the worker’s ECS model doesn’t have a

cluster

field, you’ll get “Got unexpected keyword argument 'cluster'”. Do this to diagnose and fix: 1) Dump the default ECS template your current CLI expects - This reveals the canonical set of variables for the version you’re running locally.

prefect work-pool get-default-base-job-template --type ecs --file ecs-default.json

Open

ecs-default.json

and confirm you see

cluster

referenced (you should see it under both

task_run_request.cluster

and a top-level

cluster

entry). 2) Reset your pool’s base job template to match the current version - This fixes a stale or drifted template on the pool.

prefect work-pool update "<your-ecs-pool>" --base-job-template ecs-default.json

After this, re-run a flow. If it succeeds, it was a template drift. 3) Verify deployment job_variables - Ensure your deployment passes

cluster

correctly.

prefect deployment inspect "<flow-name>/<deployment-name>"

Look for a

job_variables

section. A minimal, valid example:

job_variables:
  cluster: "my-ecs-cluster"         # name or ARN
  task_definition_arn: "arn:aws:ecs:...:task-definition/my-task:42"

4) Check the worker environment’s package versions - The worker must have compatible

prefect

and

prefect-aws

versions.

python -c "import prefect, prefect_aws; print('prefect=', prefect.__version__, 'prefect_aws=', prefect_aws.__version__)"

If these changed recently (base image refresh, auto-upgrade, etc.), pin them and restart the worker. For example:

pip install -U "prefect>=3,<4" "prefect-aws>=0.5,<2"

Tip: Keep worker and deploy-time environments aligned on the same minor versions. 5) Optional: confirm what the worker’s ECS model actually accepts - Run this inside the worker container/venv to see the live schema:

python - <<'PY'
from prefect_aws.workers.ecs_worker import ECSVariables
try:
    print(ECSVariables.model_json_schema())
except Exception as e:
    print("Failed to show schema:", e)
PY

If

cluster

isn’t in

properties

, the worker’s

prefect-aws

build is out of sync with your pool template. If you share: - The worker’s

prefect

and

prefect-aws

versions - A snippet of the pool’s base_job_template (or just confirm

cluster

is present after step 2) - The top of the stack trace …I can tell you precisely whether this is a template drift or a package mismatch and provide the exact pin or template patch to apply. Reference docs: - ECS guide: Prefect AWS ECS guide - Customize job variables: Customize job variables - Manage work pools: Manage work pools

Thanks — that explains it. If the error started right after editing the Base Job Template, the worker is likely rejecting the edited template because it no longer matches what

prefect-aws

expects. The ECS worker validates the top-level keys of `job_configuration`; if it sees a key it doesn’t know (or if keys are moved/renamed), you’ll get “TypeError: Got unexpected keyword argument 'cluster'”. Fastest way to fix 1) Regenerate the default ECS template and apply it to your pool

prefect work-pool get-default-base-job-template --type ecs --file ecs-default.json
prefect work-pool update "<your-ecs-pool>" --base-job-template ecs-default.json

Then re-apply your edits carefully. 2) Minimal checklist for your template edits Make sure all of these exist exactly as shown (paths/keys matter): - job_configuration.cluster -> "{{ cluster }}" - job_configuration.task_run_request.cluster -> "{{ cluster }}" - variables.properties.cluster exists (type: string) A minimal skeleton that must be preserved:

{
  "job_configuration": {
    "cluster": "{{ cluster }}",
    "task_run_request": {
      "cluster": "{{ cluster }}",
      "launchType": "{{ launch_type }}",
      ...
    },
    ...
  },
  "variables": {
    "type": "object",
    "properties": {
      "cluster": { "type": "string" },
      ...
    }
  }
}

Common pitfalls when editing - Renaming keys (e.g., changing

cluster

to

cluster_name

or nesting under

ecs_config

) — the worker model will reject unknown keys. - Moving fields to different sections (e.g., putting

cluster

inside

task_definition

). - Removing the top-level

cluster

or the

task_run_request.cluster

entry. - Adding extra wrapping objects around

job_configuration

. Optional: validate locally before updating the pool If you can run Python where the worker runs:

python - <<'PY'
import json
from prefect_aws.workers.ecs_worker import ECSJobConfiguration
cfg = json.load(open("ecs-default.json"))["job_configuration"]  # or your edited file
ECSJobConfiguration(**cfg)
print("Template OK")
PY

If this raises, the worker will also error. If you share the edited Base Job Template (or just the

job_configuration

section), I’ll spot the exact mismatch and suggest a minimal patch. Docs for reference: - ECS guide: Prefect AWS ECS guide - Customize job variables: Customize job variables - Manage work pools: Manage work pools

Thanks for sharing the snippet — that helps. Your template looks correct for the current default ECS template (it includes

cluster

both at the top level and inside

task_run_request

). The “Got unexpected keyword argument 'cluster'” right after editing the template usually means your worker is running a different prefect-aws version than the one your template is designed for. Concretely: - Newer templates include a top-level

job_configuration.cluster

- Some older worker versions only expect

task_run_request.cluster

and will error on the top-level

cluster

Two ways to resolve Option A — Make the template match your worker right now - Remove the top-level

cluster

field from

job_configuration

and keep only the nested one under `task_run_request`:

"job_configuration": {
  "env": "{{ env }}",
  "name": "{{ name }}",
  "labels": "{{ labels }}",
  "vpc_id": "{{ vpc_id }}",
  "command": "{{ command }}",
  "container_name": "{{ container_name }}",
  "aws_credentials": "{{ aws_credentials }}",
  "task_definition": { ... },
  "task_run_request": {
    "tags": "{{ labels }}",
    "cluster": "{{ cluster }}",          // keep this
    "overrides": { ... },
    "launchType": "{{ launch_type }}",
    "taskDefinition": "{{ task_definition_arn }}"
  }
  // NOTE: no top-level "cluster" here
}

Upload this adjusted base job template to the pool and retry a run. Option B — Upgrade your worker to match the new template - Update the worker’s environment so

prefect

and

prefect-aws

align with the default template you edited against:

pip install -U "prefect>=3,<4" "prefect-aws>=0.5,<2"

Then restart the worker. This version should accept the top-level

cluster

as in your current template. Helpful checks - Dump the default ECS template your local CLI expects:

prefect work-pool get-default-base-job-template --type ecs --file ecs-default.json

If your worker is on an older version, that default may not match what it accepts. Either upgrade the worker (Option B) or remove top-level

cluster

(Option A). - Inspect deployment job variables to ensure

cluster

is provided:

prefect deployment inspect "<flow>/<deployment>"

Look for:

job_variables:
  cluster: "my-ecs-cluster"

If you can share the worker’s versions:

python -c "import prefect, prefect_aws; print('prefect=', prefect.__version__, 'prefect_aws=', prefect_aws.__version__)"

…I can confirm whether you should remove the top-level

cluster

or upgrade the worker. Docs: - ECS guide: Prefect AWS ECS guide - Customize job variables: Customize job variables - Manage work pools: Manage work pools