docker/compose · error

archiving %q: %w

Error message

archiving %q: %w

What it means

After de-duplicating entries (last-one-wins), ArchivePathsIfExist writes each entry into the tar stream via writeEntry. Any failure inside writeEntry (header write, open, copy, flush) surfaces as 'archiving %q' for the specific entry path. It is the generic wrapper over the per-file write pipeline.

Source

Thrown at internal/sync/tar.go:167

	// (that's more in-line with how syncs work) might ignore files in earlier
	// path mappings when we know they're going to be "synced" over.
	// There's a bunch of subtle product decisions about how overlapping path
	// mappings work that we're not sure about.
	var entries []archiveEntry
	for _, p := range paths {
		newEntries, err := a.entriesForPath(p.HostPath, p.ContainerPath)
		if err != nil {
			return fmt.Errorf("inspecting %q: %w", p.HostPath, err)
		}

		entries = append(entries, newEntries...)
	}

	entries = dedupeEntries(entries)
	for _, entry := range entries {
		err := a.writeEntry(entry)
		if err != nil {
			return fmt.Errorf("archiving %q: %w", entry.path, err)
		}
	}
	return nil
}

func (a *ArchiveBuilder) writeEntry(entry archiveEntry) error {
	pathInTar := entry.path
	header := entry.header

	if header.Typeflag != tar.TypeReg {
		// anything other than a regular file (e.g. dir, symlink) just needs the header
		if err := a.tw.WriteHeader(header); err != nil {
			return fmt.Errorf("writing %q header: %w", pathInTar, err)
		}
		return nil
	}

	file, err := os.Open(pathInTar)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Identify the named entry and check whether it still exists and is readable on the host
2. Look at the wrapped %w cause to route to the specific sub-error (header vs copy vs finalize) and apply the fix for errors 105/106/107/108/109
3. Stabilize the source tree during sync (pause generators, use .dockerignore-style exclusions for volatile temp files)
4. Retry the sync; transient vanish-during-copy of adjacent files is the usual cause and a fresh walk resolves it

// verify entry set is archivable: all entries exist and are readable post-walk
for _, e := range entries {
    if fi, err := os.Stat(e.path); err != nil || fi.Mode()&0400 == 0 { exclude(e) }
}

// on 'archiving %q', inspect the wrapped cause; pipe-related causes redirect to container-side diagnosis, local causes to file fixes; then retry the whole sync

When it happens

Trigger: writeEntry failing for entry.path: tar.Writer already in an error state (a prior failed WriteHeader poisons the writer), the file was deleted after walking but is not IsNotExist-classified, or any of the copy/flush errors documented in errors 105-109 for this particular entry.

Common situations: Rapidly churning directories during watch where files vanish or change size between the walk and the copy step; a preceding entry already corrupted the writer so every following entry fails with the wrap.

Related errors

• stat %q: %w
• inspecting %q: %w
• copying %q: %w
• deleting paths in %s: %w
• copying files to %s: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/ef22ad3fd0000f2a. Report an issue: GitHub.