Fix AWS CodeDeploy 'file already exists' error

Quick answer

Add an rm -f or rm -rf command in a BeforeInstall hook to delete the conflicting file before your deployment scripts try to write it.

Here's the thing: CodeDeploy's in-place deployment doesn't automatically overwrite files that already exist on the target instance. If your appspec or a hook script tries to copy or create a file that's already sitting there—say, from a previous deployment or a manual SSH session—the agent bails out with The deployment failed because a specified file already exists at this location. This isn't a permissions issue or a network problem. The agent sees a file at the target path and simply refuses to clobber it. This bites people hard when they're deploying to an EC2 instance that's been running for a while, or when a config file was placed by hand during troubleshooting and then the next automated deploy blows up.

What's actually happening here is that CodeDeploy's built-in file installation step uses a non-overwriting copy by default. It's designed to be safe—it won't silently replace files that might have drifted. But that safety becomes a brick wall when you intentionally want to replace a config or a binary. The fix is to make the removal explicit before the agent tries to write.

Fix steps

Find the exact file path in the error message. The error will include the full path, like /var/www/html/wp-config.php. Note it down. If you don't see it, check the deployment logs at /opt/codedeploy-agent/deployment-root/<deployment-group-id>/<deployment-id>/logs/scripts.log.
Open your appspec.yml. You'll need to edit the hooks section. If there's no hooks section, you'll create one under the version: line.
Add a BeforeInstall hook that deletes the file. Use the rm -f command for a single file, or rm -rf if it's a directory. For example:
```
version: 0.0
os: linux
files:
  - source: /
    destination: /var/www/html
hooks:
  BeforeInstall:
    - location: scripts/before_install.sh
      timeout: 300
      runas: root
```
Then create scripts/before_install.sh with:
```
#!/bin/bash
rm -f /var/www/html/wp-config.php
```
Make sure the script is executable: chmod +x scripts/before_install.sh.
Commit and push your changes, then redeploy. The hook runs before CodeDeploy tries to write the file, so the path is clean and the install proceeds.

If the main fix doesn't work

Sometimes the file isn't actually there when the hook runs—maybe it's created by a later step in your own script, or the error path is inside a directory that's being moved as part of the deployment. Try these alternatives:

Move the file instead of deleting it. If you need a backup, use mv /path/to/file /path/to/file.bak in the hook. That avoids the error and keeps the old version around for rollback.
Use the --overwrite flag in your own copy commands. If you're using cp or aws s3 cp inside a hook, add --overwrite or -f to force replacement. But remember, the built-in file installation step still uses the default non-overwrite behavior, so this only helps for files you copy manually.
Switch to a Blue/Green deployment. If you're constantly fighting stale files on an instance, Blue/Green gives you a fresh instance each deployment. No leftover files, no conflict. It costs more (you run two instances briefly), but it's the cleanest solution for stateless apps.

One gotcha: if the file is owned by a different user (like www-data) and your hook runs as root, rm -f still works because root can delete anything. So don't worry about permissions unless you set runas to a non-privileged user.

Prevention

The real fix is to stop this from happening again. Two habits help:

Never manually edit files on an instance that CodeDeploy manages. That's how drift starts. If you need to change a config, change it in your repo and deploy it.
Make your deployment script idempotent. Before any write, always check if the target exists and remove it. This is a standard pattern in configuration management. For example, in your before_install.sh, loop through a list of known conflicting paths and delete them all:

#!/bin/bash
for f in /var/www/html/wp-config.php /etc/nginx/conf.d/default.conf; do
  if [ -f "$f" ]; then
    rm -f "$f"
  fi
done

That way, even if the file appears later, your deployment won't trip over it. The cost is a few seconds of script execution, but it saves you from a midnight call about a failed deploy.