twpayne/chezmoi · error

%s: unsupported mode %o

Error message

%s: unsupported mode %o

What it means

Returned during archive walk when an entry's fs.ModeType is neither a regular file, directory, nor symlink that chezmoi knows how to map into source state entries. The octal mode-type bits are included for diagnosis.

Source

Thrown at internal/chezmoi/sourcestate.go:2593

				Type:       SourceFileTypeSymlink,
			}
			sourceRelPath := NewSourceRelPath(fileAttr.SourceName(s.encryption.EncryptedSuffix()))
			targetStateEntry := &TargetStateSymlink{
				linknameFunc: sync.OnceValues(func() (string, error) {
					return linkname, nil
				}),
				sourceAttr: SourceAttr{
					External: true,
				},
			}
			sourceStateEntry = &SourceStateFile{
				attr:             fileAttr,
				origin:           external,
				sourceRelPath:    parentSourceRelPath.Join(dirSourceRelPath, sourceRelPath),
				targetStateEntry: targetStateEntry,
			}
		default:
			return fmt.Errorf("%s: unsupported mode %o", name, fileInfo.Mode()&fs.ModeType)
		}
		sourceStateEntries[targetRelPath] = append(sourceStateEntries[targetRelPath], sourceStateEntry)
		return nil
	}); err != nil {
		return nil, fmt.Errorf("%s: %s: %w", externalRelPath, urlStr, err)
	}

	return s.populateImplicitParentDirs(externalRelPath, external, sourceStateEntries), nil
}

// readExternalArchiveData reads an external archive's data and returns its data
// and format.
func (s *SourceState) readExternalArchiveData(
	ctx context.Context,
	externalRelPath RelPath,
	external *External,
	options *ReadOptions,
) ([]byte, string, ArchiveFormat, error) {

View on GitHub (pinned to f901167e46)

Solutions

1. Rebuild/repackage the external archive to contain only regular files, directories, and symlinks
2. Filter out special files from the upstream archive before hosting it
3. Switch to a different external source/mirror whose archive has only standard entries

Example fix

// before: archive includes a FIFO
$ tar -czf tool.tar.gz tool/ tool/pipe  # pipe is a fifo
// after
$ tar -czf tool.tar.gz tool/ --exclude=tool/pipe

// inspect archive for special file types before use
out, _ := exec.Command("tar", "-tvf", archivePath).Output()
for _, line := range strings.Split(string(out), "\n") {
    if strings.ContainsAny(line[:1], "pbcs") { return fmt.Errorf("special file in archive: %s", line) }
}

if err := apply(); err != nil && strings.Contains(err.Error(), "unsupported mode") {
    switchToCleanMirrorURL() // fallback external without special files
}

When it happens

Trigger: An external archive contains a special file type (e.g. device node, named pipe/FIFO, socket) which readExternalArchive's switch has no case for.

Common situations: Archive built from a full system tree including /dev entries or fifos; unusual packaging that embeds sockets; archives generated by tools that include special files.

Related errors

• %s: unknown archive format
• %s: unsupported typeflag '%c'
• %s: unsupported file mode %o
• %s: %w
• %s: unsupported mode %o

AI-assisted analysis of twpayne/chezmoi@f901167e46 (2026-09-01). Data as JSON: /api/errors/05c642bd55804e98. Report an issue: GitHub.