juicedata/juicefs · error

invalid guid-mask %q: value must be greater than zero

Error message

invalid guid-mask %q: value must be greater than zero

What it means

The guid-mask setting parsed as an integer but evaluated to zero; a zero mask would collapse every derived ID to 0. Validation guard enforcing a positive non-zero mask so uid/gid bit-masking preserves distinct identities.

Source

Thrown at sdk/java/libjfs/guid.go:35

package main

import (
	"crypto/md5"
	"encoding/binary"
	"fmt"
	"os/user"
	"strconv"
	"sync"
)

func guidMask(value, metaName string) (uint32, error) {
	if value != "" {
		mask, err := strconv.ParseUint(value, 0, 32)
		if err != nil {
			return 0, fmt.Errorf("invalid guid-mask %q: expected an unsigned 32-bit integer", value)
		}
		if mask == 0 {
			return 0, fmt.Errorf("invalid guid-mask %q: value must be greater than zero", value)
		}
		return uint32(mask), nil
	}
	switch metaName {
	case "mysql", "postgres", "sqlite3":
		return uint32(0x7FFFFFFF), nil
	default:
		return 0, nil
	}
}

type pwent struct {
	id   uint32
	name string
}

type mapping struct {
	sync.Mutex

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use a non-zero mask value such as 2147483647 (0x7FFFFFFF)

When it happens

Trigger: Thrown at sdk/java/libjfs/guid.go:35 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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