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

Check the wrapped cause message for the underlying extsort failure (usually mkdir/permission/disk-space)

create object sorter: %s

Error message

create object sorter: %s

What it means

Wraps a failure from extsort.New when constructing the second (object-record) external sorter used by `juicefs gc --sort`. extsort.New fails when it cannot prepare its work directory or spawn its I/O resources (e.g. WorkDir is not writable/creatable, or invalid Threads config). The already-created meta sorter is closed and torn down before returning.

Source

Thrown at cmd/gc_external.go:122

	})
	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
}

func scanGcMetaRecords(c meta.Context, m meta.Meta, output chan<- gcMetaRecord, metaSliceSpin *utils.Bar) error {
	st := m.ScanSlices(c, &meta.ScanSlicesOption{ScanPending: true}, func(ino meta.Ino, s meta.Slice) error {
		select {
		case <-c.Done():
			return c.Err()
		default:
		}
		metaSliceSpin.Increment()
		var state uint8
		switch ino {
		case 0:
			state = gcStatePending
		case 1:
			state = gcStateTrash

View on GitHub (pinned to c9a67b23e8)

Solutions

Check the wrapped cause message for the underlying extsort failure (usually mkdir/permission/disk-space)
Verify the --sort-dir path exists and is writable by the running user (e.g. `touch <dir>/test && rm <dir>/test`)
Free space on the filesystem backing the sort directory or pick another directory with space
Re-run `juicefs gc` once the directory is writable

Example fix

// before
juicefs gc --sort-dir /mnt/ro-volume/sort sqlite3://test.db
// after
mkdir -p /var/tmp/jfs-gc-sort && chmod u+w /var/tmp/jfs-gc-sort
juicefs gc --sort-dir /var/tmp/jfs-gc-sort sqlite3://test.db

Defensive patterns

Strategy: validation

Validate before calling

if fi, err := os.Stat(extSortDir); err != nil || !fi.IsDir() { return fmt.Errorf("sort dir unavailable: %w", err) }
if f, err := os.CreateTemp(extSortDir, ".probe"); err != nil { return err } else { f.Close(); os.Remove(f.Name()) }

Try / catch

if _, _, err := newGcExternalSorters(ctx, dir, threads); err != nil {
	log.Printf("gc aborted: %v — check sort dir %s is writable and has free space", err, dir)
}

Prevention

Provision the --sort-dir on a writable volume with ample free space
Probe writability before launching long gc runs
Run gc as a user with write access to the sort directory

When it happens

Trigger: Running `juicefs gc` in external-sort mode where extSortDir (the --sort-dir) is unwritable, does not exist and cannot be created, is on a full filesystem, or the extsort config (WorkDir/Name/Threads) is invalid such that extsort.New returns an error for the gc-object sorter after the gc-meta sorter succeeded.

Common situations: gc run in a container whose sort directory is read-only or on a tmpfs that ran out of space; --sort-dir pointing to a path the user cannot write; disk full on the sort volume; extremely small thread/resource limits.

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/5cb97667b1ae1fb3. Report an issue: GitHub.