What causes "create meta sorter: %s" in juicedata/juicefs?

Ensure the --ext-sort directory exists and is writable: `mkdir -p && touch /.probe`.

create meta sorter: %s

Error message

create meta sorter: %s

What it means

Wrapped error from newGcExternalSorters when creating the meta record external sorter (extsort.New) fails — before any scan starts. Typical causes are problems with the work directory or sorter config, so GC in external-sort mode cannot proceed and exits early with this message.

Source

Thrown at cmd/gc_external.go:106

	if sortErr != nil {
		return sortErr
	}
	return nil
}

func newGcExternalSorters(ctx context.Context, extSortDir string, threads int) (*extsort.Sorter[gcMetaRecord], *extsort.Sorter[gcObjectRecord], error) {
	metaSorter, err := extsort.New(ctx, extsort.Config{
		WorkDir:  extSortDir,
		Name:     "gc-meta",
		Threads:  threads,
		Checksum: true,
	}, extsort.Codec[gcMetaRecord]{
		FromBytes: gcMetaRecordFromBytes,
		ToBytes:   gcMetaRecordToBytes,
		Compare:   compareGcMetaRecord,
	})
	if err != nil {
		return nil, nil, errors.Errorf("create meta sorter: %s", err)
	}

	objSorter, err := extsort.New(ctx, extsort.Config{
		WorkDir:  extSortDir,
		Name:     "gc-object",
		Threads:  threads,
		Checksum: true,
	}, extsort.Codec[gcObjectRecord]{
		FromBytes: gcObjectRecordFromBytes,
		ToBytes:   gcObjectRecordToBytes,
		Compare:   compareGcObjectRecord,
	})
	if err != nil {
		metaSorter.CloseInput()
		_ = metaSorter.Done()
		return nil, nil, errors.Errorf("create object sorter: %s", err)
	}
	return metaSorter, objSorter, nil

View on GitHub (pinned to c9a67b23e8)

Solutions

Ensure the --ext-sort directory exists and is writable: `mkdir -p <dir> && touch <dir>/.probe`.
Check permissions of the directory for the user running juicefs.
Fix the path typo if the directory doesn't exist.
Avoid read-only mounts/containers for the sort dir; mount a writable volume.
If threads config is suspect, retry with default --threads.

Example fix

// before
juicefs gc --ext-sort /nonexistent-dir $META
// after
mkdir -p /var/jfs-extsort && juicefs gc --ext-sort /var/jfs-extsort $META

Defensive patterns

Strategy: validation

Validate before calling

DIR=$EXT_SORT_DIR; [ -d "$DIR" ] && [ -w "$DIR" ] && touch "$DIR/.probe" && rm "$DIR/.probe" || { echo "ext-sort dir missing or unwritable: $DIR"; exit 1; }

Try / catch

if strings.Contains(out, "create meta sorter:") {
    // ext-sort WorkDir problem: verify path exists and is writable before retry
}

Prevention

Always mkdir and permission-check the --ext-sort directory before running
Avoid read-only mounts for temp sort dirs
Keep --threads at supported defaults unless tuned

When it happens

Trigger: `juicefs gc --ext-sort <dir>` where extsort.New fails: the WorkDir doesn't exist or isn't writable, filesystem errors creating the sorter's temp files, or an invalid config (e.g. non-positive threads).

Common situations: Passing --ext-sort a path on a read-only or non-existent directory; running in a container with a read-only rootfs; permission-denied on the sort dir; typo in the directory path.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/bec59828abdd3fdf. Report an issue: GitHub.