Linux / shell

Text file busy — the running executable is still the file you are overwriting

Written and reviewed by Sahil Srivastav

ETXTBSYDeploymentsExecutable lifecycle

cp: cannot create regular file '/srv/app/bin/server': Text file busy

What this error actually means

Despite its name, Text file busy usually concerns an executable image, not an ordinary text document. Linux can reject opening a currently executing binary for writing. The reverse can also fail: execution is rejected while the file is open for writing. Both protect the relationship between an executable’s contents and a process using that image.

The important identity is the underlying file, not merely its pathname. Copying new bytes over /srv/app/bin/server attempts to modify the object that running processes may still execute. Creating a different file and renaming it into that pathname changes the directory entry; existing processes can retain the old object while future executions resolve the new one.

This makes a deployment race look intermittent. A copy, antivirus integration, build step or artifact writer may still hold a write descriptor when a launch begins. Retrying after a delay can conceal the ordering bug but does not make the release sequence correct. The writer must complete and close before the artifact becomes executable input.

Causes, most common first

1The release process overwrites a running binary in place. A direct copy to the active executable path may open and truncate the current file. Linux rejects that write while the image is in use. Updating by pathname is not automatically an atomic artifact replacement.
2A build or download is still writing when launch starts. A pipeline starts the executable before its producer closes the output file. Even complete-looking file contents are insufficient evidence: an open writable descriptor can remain after the last visible write.
3Deployment steps race across workers. Two release jobs can copy, rename and restart the same service concurrently. One worker launches a file that the other still has open. The problem needs coordination around release publication, not a larger sleep between commands.
4The deployment assumes local-filesystem semantics everywhere. Network or specialised filesystems can add different replacement and caching behaviour. Confirm where the binary lives. A procedure validated on a local filesystem should not be assumed correct on every shared mount.

When you see it

A deployment fails while copying over a live service binary
A newly generated executable runs on retry after its writer has finished
Stopping the service makes an in-place overwrite succeed
Changing permissions has no effect on the busy-file error

How to diagnose it

Step 1

Identify processes referring to the executable

lsof and fuser can show users of the active path. Run with enough visibility to inspect the service. Preserve the output before a restart; after recovery the evidence of the conflicting writer may be gone.

lsof /srv/app/bin/server
fuser -v /srv/app/bin/server

Step 2

Compare the running image with the published path

Replace 1234 with the service PID. stat -L follows the executable symlink and reports device and inode. Different identities mean the pathname has already been replaced while the process still runs an older object.

readlink /proc/1234/exe
stat -Lc '%d:%i %n' /proc/1234/exe /srv/app/bin/server

Step 3

Inspect the mount and deployment sequence

Confirm whether the temporary artifact and destination are on the same filesystem. Read the release script for direct overwrite, background copy jobs, or launch before wait. If a writer is asynchronous, successful launch must depend on its completed exit status.

findmnt -T /srv/app/bin/server -o TARGET,FSTYPE,OPTIONS

Step 4

Reproduce the file-lifecycle conflict in staging

Use a disposable executable copy and a controlled writer to distinguish an active-image overwrite from launch-while-writing. Do not experiment on the production binary. The meaningful proof is which process holds the conflicting file open.

The fix

Build or download into a distinct temporary file in the destination filesystem, close the writer, validate the artifact and set its final ownership and mode. Publish it with a same-filesystem rename. A rename replaces the pathname atomically, whereas a move across filesystems may become a copy and lose that property.

The example stages a trusted binary next to the destination, then publishes it. It assumes a single coordinated deployer, an existing writable /srv/app/bin directory, and acceptable deploy-user ownership. Incorporate signature or checksum verification before mv in your release pipeline. Do not overwrite the temporary file again once published.

Restart or roll the service after publication and verify its loaded version. Existing processes continue with the old image; replacing the pathname does not upgrade them in memory. Keep immutable versioned artifacts when rollback and auditing matter, and coordinate configuration compatibility with the binary release.

Atomic visibility is not crash durability. If deployment must survive a power loss at every step, use a release mechanism that also performs the required file and directory synchronisation. Treat that as a separate property rather than claiming rename alone guarantees durable installation.

#!/bin/bash
set -e
release_tmp=$(mktemp /srv/app/bin/.server.XXXXXX)
trap 'rm -f -- "$release_tmp"' EXIT
cp -- ./build/server "$release_tmp"
chmod 0755 "$release_tmp"
# Validate this staged artifact before publication.
mv -f -- "$release_tmp" /srv/app/bin/server
trap - EXIT

How to stop it coming back

Publish immutable artifacts and serialize release publication for each service.
Wait for every background writer and inspect its result before making an artifact available for execution.
Verify both the path’s published version and the running process’s version after rollout.

Practise production debugging in a real repository

Reading about a failure and reproducing one are different skills. Gronex ships broken backend repositories with failing test suites that encode the real invariant, so you debug from evidence instead of memorising symptoms.

FAQ

Will chmod 777 release the file?

No. ETXTBSY concerns executable use and writable opens, not insufficient mode bits. Broadening permissions leaves the conflicting file lifecycle unchanged.

Why does deleting or renaming the old path work?

A directory entry and an open file reference are different. Removing or replacing the name can leave the old file object available to a process already using it. That is why publication can be atomic without modifying the active image.

Is this the same as a locked text document?

No. The historical word text refers to executable code. Advisory application locks and editor lockfiles have different mechanisms, and killing arbitrary editors will not repair a release that overwrites a running binary.

Permission denied on exec Bash deployment hardening practice

Other errors engineers hit next to this one

Full error and symptom index →