juicedata/juicefs · error

invalid guid-mask %q: expected an unsigned 32-bit integer

Error message

invalid guid-mask %q: expected an unsigned 32-bit integer

What it means

Returned by guidMask in the Java SDK's native library when the guid-mask option is set but is not parseable as an unsigned 32-bit integer. The mask constrains generated uid/gid values; a non-numeric or out-of-range value is rejected at init.

Source

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

 * limitations under the License.
 */

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
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Set guid-mask to a valid unsigned 32-bit integer, e.g. 0x7FFFFFFF, or omit it

When it happens

Trigger: Thrown at sdk/java/libjfs/guid.go:32 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/1960cf8883240fcc. Report an issue: GitHub.