hyperledger/fabric · error

refusing to copy unsupported file %s with mode %o

Error message

refusing to copy unsupported file %s with mode %o

What it means

CopyDir walks a source directory (e.g. an external builder's release artifacts) and copies directories, regular files, and symlinks. When it encounters a filesystem node that is none of these - a device file, socket, FIFO, or other special file - it deliberately refuses to copy it and returns this error, then removes everything it already copied to the destination. This is a safety guard so special files are not silently reproduced.

Source

Thrown at core/container/externalbuilder/copy.go:46

			return err
		}
		destpath := filepath.Join(destroot, srcsubpath)

		switch {
		case info.IsDir():
			return os.MkdirAll(destpath, info.Mode())
		case info.Mode()&os.ModeSymlink == os.ModeSymlink:
			// filepath.Walk does not follow symbolic links; we need to copy
			// symbolic links as-is because some chaincode types (Node.js) rely
			// on the use of symbolic links.
			return copySymlink(srcroot, path, destpath)
		case info.Mode().IsRegular():
			// Intermediate directories are ensured to exist because parent
			// node is always visited before children in `filepath.Walk`.
			return copyFile(path, destpath)
		default:
			// It's something else that we don't support copying (device, socket, etc)
			return errors.Errorf("refusing to copy unsupported file %s with mode %o", path, info.Mode())
		}
	})
	// If an error occurred, clean up any created files.
	if err != nil {
		if err := os.RemoveAll(destroot); err != nil {
			logger.Errorf("failed to remove destination directory %s after copy error: %s", destroot, err)
		}
		return errors.WithMessagef(err, "failed to copy %s to %s", srcroot, destroot)
	}
	return nil
}

func copySymlink(srcroot, srcpath, destpath string) error {
	// If the symlink is absolute, then we do not want to copy it.
	symlinkDest, err := os.Readlink(srcpath)
	if err != nil {
		return err
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Locate the reported path and delete it: 'find <srcroot> ! -type f ! -type d ! -type l' to find sockets/FIFOs/devices.
2. Clean and rebuild the chaincode package so build byproducts (sockets, pipes) are not included.
3. Add the offending artifact generation to a .gitignore/clean step or exclude it from the packaged source.
4. If the file is required, replace it with a regular file or have the build script recreate the socket at runtime.

Example fix

// before: package dir contains server.sock left by a test run
// after
$ find . ! -type f ! -type d ! -type l -delete
$ # repackage the chaincode

// shell: detect special files in a package before install
// find <pkgdir> ! -type f ! -type d ! -type l -print
// exit non-zero if any are found

// Go caller of CopyDir
if err := CopyDir(logger, src, dst); err != nil {
    if strings.Contains(err.Error(), "refusing to copy unsupported file") {
        // clean the reported path and re-run the build/package step
    }
}

When it happens

Trigger: filepath.Walk over srcroot hits a node whose mode is not IsDir, not a symlink, and not IsRegular - e.g. a Unix domain socket or named pipe left inside the builder source/release directory.

Common situations: Build processes that leave .sock files or FIFOs in the package directory; node_modules containing sockets; dev artifacts copied into a chaincode package by mistake.

Related errors

• refusing to copy absolute symlink %s -> %s
• failed writing file %s: %v
• error writing output
• error writing config update to output
• error opening block file %s

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/fda812cbab2759a8. Report an issue: GitHub.