What the agent does
Celery 5 rewrote its command line on Click, and -A became a global option that must come before the subcommand. A Procfile or Compose service that still runs celery worker -A proj ... stops at once: the current release, 5.7.0, prints a notice that the usage was removed in Celery 5.0 and shows the new order, then Usage: celery worker [OPTIONS], Try 'celery worker --help' for help. and Error: No such option '-A'., exit code 2. The worker never connects to the broker, so the queue silently fills while the web process keeps answering.
DCAStack/DCAStackCefi, a Flask app that runs scheduled exchange orders through Celery and Redis, has the command in two places. Procfile line 2 starts the worker with celery worker -A celery_worker.celery --beat --loglevel=info --concurrency=4, and docker-compose.yml line 22 runs celery worker -A celery_worker.celery -f celeryLogs.log --loglevel=info --concurrency=4 for the worker service. Line 35 of the same file already has the new order, celery -A celery_worker.celery beat, which is how most repositories look after a partial migration: the beat process starts and the worker does not. requirements.txt pins celery==4.4.7 beside Flask==2.0.2 and redis==3.5.3, the Dockerfile builds on python:3.8, and celery_worker.py imports the celery object that project/__init__.py line 30 creates with Celery(__name__, broker=Config.CELERY_BROKER_URL).
The agent first explains why the pin has to move, because that decides whether this is a one-line fix. In a clean environment on the Python the host now offers, celery==4.4.7 installs but import celery fails inside its vine dependency with ImportError: cannot import name 'formatargspec' from 'inspect', a function Python 3.11 removed. So a base image that moved past 3.10 forces Celery 5, and with Celery 5 the Procfile command fails with the error in the title. Both outputs go in the pull request.
Then it changes the commands and proves they parse. Each celery worker -A X ... becomes celery -A X worker ..., and every other flag stays where it is: the agent checks celery -A celery_worker.celery worker --help on the new release and confirms -f, --logfile, -B, --beat, -l, --loglevel, -c, --concurrency, -Q, --queues, -n, --hostname and --pidfile are still worker options, so the reordered lines parse with exit code 0 where the old ones exited 2. It raises the pin to the Celery 5 release it tested, keeps redis and flower on versions that resolve beside it, and reads project/__init__.py for settings that Celery 5 renamed, such as the upper-case CELERY_BROKER_URL keys that celery.conf.update(app.config) copies in on line 76, reporting any that need a new name rather than guessing.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Our Celery worker no longer starts: the process exits with Error: No such option '-A' right after printing the celery worker usage. Read every place a worker or beat is started (Procfile, docker-compose files, Dockerfiles, systemd units, shell scripts, CI and README) and list each command with its file and line. Read the dependency files and report the pinned Celery version and the Python version the host uses. In a clean virtual environment on that Python, install the pinned Celery and import it, and separately install the current Celery 5 release and run the exact worker command from the Procfile; include both outputs so the pull request shows why the pin must move and what fails afterwards. Rewrite each start command for Celery 5 by moving -A (or --app) and any other global option in front of the subcommand, keeping every worker flag as it is. For each rewritten command, run it with --help on the new release to prove it parses, and include that output. Raise the Celery pin to the release you tested and adjust redis, kombu and flower pins only as far as the resolver requires. Read the Celery configuration in the app factory for setting names Celery 5 renamed and list any that need attention, without changing behaviour you cannot test. Do not connect to a broker and do not run tasks. Open a pull request that lists every changed line, the versions installed, and what could not be verified without a broker.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes the start commands and the requirements file, and nothing in the task code. Its description opens with the two reproductions: the import error from the old pin on the current Python, and the No such option '-A' output from the unchanged Procfile line on Celery 5. Below that is a table of every start command with its file, line, old form and new form, and for each the --help run that shows the new form parses.
A reviewer checks the flags one by one against the old lines, because that is where a migration like this goes wrong: a -f log path or a -Q queue list that was dropped in the rewrite would start a worker that logs to the wrong place or consumes the wrong queue. The versions section names the Celery release that was installed and which transitive pins the resolver moved.
The description ends with what stayed unverified. The run never had a broker, so the worker was proven to parse, not to consume, and the first real start is for the reviewer to watch in a staging environment before merging.
Run it on every Procfile or Compose change
The break arrives with a base image bump or a dependency upgrade, not with a change to the worker command, so the check belongs on every change to the files that start processes. Give the repository's Project an automation with a github trigger on pull_request.closed.merged, its branch_patterns set to your default branch, and a prompt that asks the agent to run every Celery start command it finds with --help on the pinned release and open a pull request only when one fails to parse. The merged pull request's details are added after the prompt as event text.
If the first sign is still an alert from your host, a scheduler like Heroku or a Compose stack that restarts the worker in a loop, forward it from a handler on your server to a webhook trigger on the same automation with Authorization: Bearer and the trigger's secret, and the handler's text follows the prompt as the event.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
The fix is a reordering of one line, and that is exactly why it ships broken so often: nobody starts the worker locally, the beat process comes up fine, and the failure is a crash loop in a dashboard. The agent runs the real command on the real release and keeps the output. The pull request then carries proof that the old line fails and the new line parses, with every flag accounted for, instead of a reviewer's memory of the Celery 5 syntax.
The sandbox also settles the question that comes before the fix: whether staying on Celery 4 was ever an option. Installing the old pin on the Python the host now runs, and watching the import fail inside vine, is two commands and some debris nobody wants in a laptop environment. In a run it is captured once and cited in the description, so the version bump is shown to be forced rather than chosen.
Frequently asked questions
Why did only the worker break while beat kept running?
Because the two commands were migrated at different times. In the example repository the beat line already reads celery -A ... beat while the worker line still reads celery worker -A .... Celery 5 accepts the first and refuses the second, so the schedule ticks and nothing consumes the queue.
Can I stay on Celery 4 instead?
Only on an older Python. In the run, celery==4.4.7 installed on Python 3.11 but failed to import because its vine dependency uses inspect.formatargspec, which that Python removed. If your base image or host moved past 3.10, the pin has to move with it.
Do my worker flags still work after the reorder?
The ones in the example all do: --beat, --loglevel, --concurrency, -f for the log file, -Q, -n and --pidfile are listed by celery worker --help on 5.7.0. The agent runs each rewritten command with --help so a flag Celery 5 dropped shows up as an error in the run, not in production.
Will it rename my Celery settings too?
It reads the app factory and lists settings Celery 5 renamed, with the old and new names, but changes only what it can test without a broker. Upper-case keys copied in with conf.update still work in Celery 5 with a deprecation notice, so a rename is a separate, reviewable change.
Does the agent connect to Redis or run tasks?
No. The request forbids a broker connection, and proving the command line only needs --help. The first real start, with the broker URL from your environment, is for the reviewer in staging.