# Fix "docker-compose: command not found" in GitHub Actions

Yes. An agent switches each workflow step from docker-compose to docker compose, checks the flags and the Compose file under v2, and updates the docs to match.

[Run this on Rush](https://cloud.getrush.ai/run/fix-docker-compose-command-not-found/github-actions/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

GitHub's hosted Ubuntu runners used to ship two Compose commands: the standalone `docker-compose` binary, which is Compose v1, and the `docker compose` plugin, which is v2. The v1 binary was removed from the runner images in 2024. A workflow that had passed for years then fails on the step that calls it, with `docker-compose: command not found` and exit code 127, without a single commit to the repository. The fix is a space where the hyphen was. Doing it properly means finding every place the old command is typed and confirming that v2 treats the project's Compose file and flags the same way.

fh1ch/node-bacstack shows the shape. Its `.github/workflows/ci.yml` has a `compliance` job on `ubuntu-latest` with two steps: `actions/checkout@v2`, then `run: docker-compose up --abort-on-container-exit --exit-code-from bacnet-client`. The `docker-compose.yml` beside it defines a `bacnet-device` service from a published image and a `bacnet-client` service built from the repository's `Dockerfile`, joined with `links`. The same command appears a second time in `CONTRIBUTING.md`, after `docker-compose build`, as the way to run the compliance tests locally. The agent changes all three occurrences, because a workflow that says one thing and a contributor guide that says another is how the next person reintroduces the hyphen.

Before trusting the edit it checks what v2 does with this file. It runs `docker compose config` to see the resolved project and reads the warnings: this file starts with `version: '3'`, a key current Compose releases report as obsolete and ignore. It confirms that the two flags the job depends on exist in v2 with the same meaning, since `--exit-code-from bacnet-client` is what turns a failing test container into a failing job. It looks for anything that depends on v1's container naming, where names were joined with underscores and v2 uses hyphens; a later step that runs `docker logs project_service_1` would break. This workflow has none. The test code addresses the other container as `bacnet-device`, the service name, which resolves the same under both versions.

The agent's sandbox has no Docker, so it installs it first with `sudo apt-get install -y docker.io` and starts `dockerd`. That package does not include the v2 plugin, which is the thing under test, so it also downloads a Compose v2 release binary into `~/.docker/cli-plugins/` before running anything. With both in place it runs the exact command from the workflow. If the published device image can no longer be pulled, or the build fails for a reason unrelated to Compose, such as the `node:16-alpine` base in the `Dockerfile` or a lockfile problem, it reports that as a separate finding with the output and still delivers the command fix.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "A GitHub Actions job fails with \"docker-compose: command not found\" (exit code 127) because hosted runners no longer include Compose v1. Find every use of the docker-compose command in this repository: workflow files under .github/, composite actions, shell scripts, Makefiles, package.json scripts, and documentation such as README and CONTRIBUTING. Replace each with the v2 form, docker compose, keeping every flag and argument. Do not rename any docker-compose.yml file; only the command changes. Do not add a step that installs Compose v1, and do not add a third-party action to provide it. Then check v2 compatibility: run docker compose config for each Compose file and report its warnings; confirm each flag used in the workflows exists in v2; search for anything that depends on v1 container names with underscores (docker logs, docker exec, docker inspect, wait scripts, hard-coded hostnames) and update those to the v2 hyphenated names or, better, to docker compose logs and docker compose exec with the service name. Install Docker and the Compose v2 plugin in your environment and run the exact commands from the changed workflow steps. Include the commands and their output. If a command fails for a reason that is not the Compose version, such as an image that cannot be pulled or a build error, report it separately with the output and do not attempt a wider fix. List, without changing, any other step in the same workflows that relies on software GitHub has removed or deprecated on hosted runners. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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 same token in several files. For a repository like the example it is three lines: one in the workflow and two in the contributor guide. The description lists each file and line, so a reviewer can confirm nothing was missed by searching the branch for the hyphenated command and finding only file names such as `docker-compose.yml`.

The description also carries what the agent learned by running the job's command under v2: the `docker compose config` warnings, the result of the command itself, and its exit code. Where the run exposed a second problem, it is in its own section with the failing output, because the workflow may stay red after this merge for that other reason and the reviewer should know before they see it.

The check that settles it is the workflow's own run on the pull request. The step that previously ended at exit code 127 should now get as far as starting containers. The reviewer looks at that step's log, not only at the summary icon, to see that Compose ran and that the job's result now reflects the tests.

## Run it on every failed workflow run

Add an automation to the Project with a `github` trigger on `workflow_run.failure` and the prompt above. When a workflow in the repository fails, Rush starts a run and places the event after the prompt as text. The prompt already tells the agent what to look for, so on a failure with a different cause it should report that it found no use of the old command and stop.

Set `branch_patterns` on the trigger to your default branch if you only want failures there, and keep max runs per hour low: a broken workflow fails on every push, and one pull request is enough. Runs from forks never fire the trigger, so a contributor's failing fork build starts nothing.

## Why run it on Rush?

The change is trivial to type and awkward to test from a developer machine, because most laptops still have a `docker-compose` shim that makes the old command work. The failure only exists where v1 is truly absent. The agent sets up exactly that environment, Docker with the v2 plugin and no v1 binary, and runs the workflow's command there, so the output in the pull request comes from the same conditions the runner has.

It also finishes the search. The hyphenated command hides in scripts that workflows call, in `Makefile` targets and in onboarding documents, and a fix that touches only the failing step leaves the rest to fail later or to mislead a new contributor. One run covers the repository and returns a list of every occurrence it changed, with the commands it executed kept in the session record.

## Frequently asked questions

### Do I need to rename docker-compose.yml?

No. Compose v2 still reads `docker-compose.yml` and `docker-compose.yaml`, and also accepts `compose.yaml`. Only the command changes, from `docker-compose` to `docker compose`. The agent leaves file names alone.

### Can I install docker-compose v1 on the runner instead?

You can add a step that downloads it, and some workflows do. Compose v1 no longer receives updates, so that keeps the job tied to software that is no longer maintained and adds a download to every run. Switching the command removes the dependency.

### Will my flags still work with docker compose?

The common ones do, including `up -d`, `--build`, `--abort-on-container-exit`, `--exit-code-from`, `-f` and `run --rm`. The agent checks each flag your workflows use against v2 and runs the commands, so a difference shows up in its report and not in your next push.

### What else changes between v1 and v2?

Container names use hyphens where v1 used underscores, so `app_web_1` becomes `app-web-1`. Scripts that call `docker logs` or `docker exec` with a full container name need updating. Using `docker compose logs web` or `docker compose exec web` avoids the name entirely, and that is the form the agent writes.

### Does this apply to self-hosted runners?

Only if v1 is missing there too. A self-hosted runner has whatever you installed, and the agent cannot see it. The v2 command works on any runner with a current Docker installation, so the change is safe to make either way.

## More GitHub Actions jobs

- [Fix a Failing check-dist Job in a TypeScript GitHub Action](https://getrush.ai/run/fix-failing-ci/github-actions/)
- [Fix "Node.js 20 actions are deprecated" Annotations in GitHub Actions Workflows](https://getrush.ai/run/fix-node-js-20-actions-are-deprecated/github-actions/)
- [Fix "The set-output command is deprecated" in GitHub Actions Workflows](https://getrush.ai/run/fix-set-output-deprecation/github-actions/)

## More jobs like this: Fix a bug from an alert

- [Fix `Call to undefined function each()` on PHP 8](https://getrush.ai/run/fix-each-function-removed/php/)
- [Fix "'xml.etree.ElementTree.Element' object has no attribute 'getchildren'" in Python 3.9+](https://getrush.ai/run/fix-elementtree-getchildren-attribute-error/elementtree/)
- [Fix "TypeError: db.collection(...).ensureIndex is not a function" after a MongoDB driver upgrade](https://getrush.ai/run/fix-ensureindex-is-not-a-function/mongodb/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
