juicedata/juicefs · error

--tier should be between 0 and 3

Error message

--tier should be between 0 and 3

What it means

The `juicefs tier` command validates the --tier flag with a cli flag Action callback. Storage classes map to tiers 0-3 (0 reserved for the default tier), so any --tier value outside that range is rejected before the command runs. This is a fail-fast CLI argument validation error.

Source

Thrown at cmd/tier.go:78

				Action:    setTier,
			},
			{
				Name:      "restore",
				Usage:     "restore objects of a file or directory",
				ArgsUsage: "META-URL PATH",
				Action:    objRestore,
			},
		},
		Flags: []cli.Flag{
			&cli.IntFlag{
				Name:  "tier",
				Usage: "tier (0-3, 0 is reserved for default tier)",
				Action: func(ctx *cli.Context, v int) error {
					if !ctx.IsSet("tier") {
						return nil
					}
					if v < 0 || v > 3 {
						return fmt.Errorf("--tier should be between 0 and 3")
					}
					return nil
				},
			},
			&cli.BoolFlag{
				Name:    "recursive",
				Aliases: []string{"r"},
				Usage:   "recursively set storage tier for all files and directories under the target directory",
			},
			&cli.BoolFlag{
				Name:    "force",
				Aliases: []string{"f"},
				Usage:   "force rewriting objects to the tier's current storage class (useful after --storage-class config changes), even when the tier id is unchanged",
			},
			&cli.IntFlag{
				Name:  "days",
				Value: object.DefaultRestoreDays,
				Usage: "the duration within which the restored object remains in the restored state",

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Use a tier value between 0 and 3 inclusive.
2. Check the volume's configured storage classes (`juicefs config`) to map the desired storage class to a valid tier.
3. If a higher tier is genuinely needed, the range must be changed in cmd/tier.go and the volume's tier configuration — this is a code/config change, not a CLI workaround.

Example fix

// before
juicefs tier sqlite3://test.db --tier 5
// after
juicefs tier sqlite3://test.db --tier 3

if tier < 0 || tier > 3 {
    return fmt.Errorf("--tier must be 0-3, got %d", tier)
}

When it happens

Trigger: `juicefs tier <meta-url> --tier 4` (or any negative value, e.g. --tier -1).

Common situations: Users guessing at tier numbering from an object store's storage-class IDs (which may exceed 3); scripting the command with a computed tier that overflows the range; typos such as --tier 13.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• --days should be at least 1
• tier should be between 0 and 3
• Invalid trash days: %d
• negative duration for %s: %s
• negative value for %s: %d

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