Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

tar: 'file changed as we read it' and exit status 1 in backup scripts

Technical article
Backup & Recovery

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

When GNU tar prints "file changed as we read it" and finishes with exit status 1, it is telling you that some files were modified while it was archiving them, so the archive does not contain an exact copy of those files. The archive is still produced and exit 1 is not a fatal error, but the files named may be inconsistent. For log files that can be tolerable. For a database, a mail store or any set of files that must agree with each other, it is not. The reliable fix is to archive from a stable view of the data, such as a snapshot, not to hide the message.

What the error means

The tar manual page (tar(1) on man7.org, dated 11 June 2026) defines the exit codes in its return value section:

  • 0: "Successful termination."
  • 1: "Some files differ." For --create, --append or --update this means "some files were changed while being archived and so the resulting archive does not contain the exact copy of the file set."
  • 2: "Fatal error. This means that some fatal, unrecoverable error occurred."

The page adds that if a subprocess invoked by tar exits with a non-zero code, "tar itself exits with that code as well", for example when an external compressor used with -z fails. So before you assume exit 1 means a changed file, confirm the "file changed as we read it" message is actually in the output.

The message comes from the warning keyword file-changed, which the page lists as %s: file changed as we read it. Two neighbouring keywords describe related conditions: file-shrank, "%s: File shrank by %s bytes; padding with zeros", and file-removed, "%s: File removed before we read it". The shrank case is worth noticing, because tar pads the file with zeros to keep the archive structure intact. The page does not describe a growing file or any other recovery behaviour, so do not assume more than the exit code and message tell you.

Why can this matter so much? tar reads files one after another over minutes or hours. The PostgreSQL documentation makes the point strongly for databases: in File System Level Backup it says the database server "must be shut down in order to get a usable backup" when tar is used, because "tar and similar tools do not take an atomic snapshot of the state of the file system, but also because of internal buffering within the server". A tar archive of a running database is a mix of files from different moments, even when each file individually looks fine.

Likely causes

Cause What you see How to confirm
Active log files and caches in the archived tree Exit 1; "file changed as we read it" for *.log or cache paths The named files are written continuously by a service
A running database or message store archived as plain files Exit 1 naming data files or journal files The paths belong to a database or mail data directory
Files deleted during the run (temporary files, rotated logs) File removed before we read it The paths are transient
A file truncated while being read File shrank by <n> bytes; padding with zeros Message text; the file is rewritten by a process
A wrapper script that stops on any non-zero status Backup reported as failed although an archive exists The archive exists and the only message is the warning
A compressor or other subprocess failed Non-zero exit with no "changed" message The output shows a compressor error instead

Prove the cause before changing anything

Read-only checks. These come from the tar manual page and have not been run.

  1. Run it once with the output saved, and record the exit status. The manual page describes --verbose as "Verbosely list files processed" and --totals as "Print total bytes after processing the archive". A typical wrapper captures $? straight after the tar line.
  2. List the files named in "file changed" messages. Group them by directory. If every one is under a log or cache path, the exposure is small. If any is a database, journal, mail store or application data file, the archive is not a trustworthy copy of that data.
  3. Find which processes write to those paths. If a service is writing to them, the next question is whether it can be quiesced or snapshotted (see Fix).
  4. Check the exit code is tar's own. Look for compressor errors in the same output.

Example (illustrative). A nightly script on APP02 runs tar -cf /backup/app02.tar /var/lib/app /var/log and the log shows two file changed as we read it lines, both under /var/log/app/, and exit status 1. The data directory under /var/lib/app does not appear in any message. The warning concerns two log files being appended to; the archive of those two logs may end mid-line, and the rest is intact. If one of the lines had named a file under /var/lib/app, the run could not be trusted for that application.

Fix

Understand what muting does first. The manual page documents --warning=KEYWORD, where messages "are suppressed if KEYWORD is prefixed with no-". So --warning=no-file-changed removes the message. The page does not say the exit status stays at 1 or changes when the warning is muted, so test that on your version before relying on either. More importantly, the files are still changing while they are read. Muting hides the message; it does not make the archive consistent. The keyword applies to the whole run, not to one path, so where you can, exclude the paths you have decided are safe to miss (application logs, for example) and leave the warning on for everything else.

For logs and caches. Exclude them. The manual lists --exclude=PATTERN, "Exclude files matching PATTERN, a glob(3)-style wildcard pattern", and the related Linux exclusions article covers what to leave out.

For data that must be consistent, archive a stable copy. Two approaches:

  • Stop or quiesce the writer. The PostgreSQL page says a shutdown is required for a tar-style file backup, and that "half-way measures such as disallowing all connections will not work".
  • Take a snapshot and archive from it. The PostgreSQL page describes the alternative of a consistent snapshot of the data directory, which works while the server runs, though "a backup created in this way saves the database files in a state as if the database server was not properly shut down", so the server replays its write-ahead log on startup, and the WAL files must be in the backup. It also warns that "If your database is spread across multiple file systems, there might not be any way to obtain exactly-simultaneous frozen snapshots of all the volumes." For LVM, the lvcreate manual page shows creating a snapshot (lvcreate --snapshot --size 100m --name mysnap vg00/mylv), notes that "often 20% of the origin LV is enough" for the copy-on-write space, and says to monitor usage and extend it if space runs low. Mount the snapshot, run tar against the mount, and remove the snapshot afterwards. The page does not say what happens if the snapshot fills, so size and monitor it.
  • Freezing. The fsfreeze manual page says freezing is meant for hardware RAID devices that support snapshots, and that "fsfreeze is unnecessary for device-mapper devices. The device-mapper (and LVM) automatically freezes a filesystem on the device when a snapshot creation is requested." While a file system is frozen, "any process attempting to write to the frozen filesystem will block", so keep the frozen window as short as you can.

For database servers, prefer the database's own backup tool, because file-level tar is documented as unsuitable on a running server.

Wrapper scripts. Do not map every exit 1 to success. A defensible rule: after tar returns 1, check that every changed file is under a path you have approved (logs, caches); if any other path is named, treat the run as failed.

Confirm the fix

  • The run completes with exit 0, or exit 1 with warnings only for approved paths.
  • If you used a snapshot, the archive was taken from the snapshot mount and the snapshot has been removed.
  • Restore the archive to a scratch location and start the application or database against the restored copy. For a database, that restore test is the real proof, since a consistent-looking archive can still need log replay.

What to watch afterwards

  • A change in the list of files named in "changed as we read it" messages, especially a data path appearing.
  • Archive sizes that fall suddenly, or File shrank by messages.
  • Snapshot space: monitor it so it does not run out while tar is reading.
  • Any new service that writes into a directory you already archive.

Risks and limits

  • These commands have not been run or lab-tested. They come from the tar, PostgreSQL, LVM and fsfreeze manual pages.
  • The behaviour described here is taken from the Linux man-pages rendering of GNU tar's manual page.
  • The manual page does not say whether --warning=no-file-changed changes the exit status. Test it on your version before you depend on it.
  • The PostgreSQL guidance is for PostgreSQL 18. Other databases have their own rules; check the vendor documentation.
  • A snapshot gives a crash-consistent view at best. Whether that is enough depends on the application.

Sources