juicedata/juicefs · error

tier should be between 0 and 3

Error message

tier should be between 0 and 3

What it means

This is a flag-level Action validator for the `--tier` option of `juicefs config`. It rejects any tier value outside 0-3, since JuiceFS only defines four data tiers. The error surfaces before any config change is applied.

Source

Thrown at cmd/config.go:121

		&cli.DurationFlag{
			Name:        "changelog-max-age",
			Usage:       "max age of changelog entries (e.g. 2h, 30m); 0 to disable time-based cleanup",
			Value:       2 * time.Hour,
			DefaultText: "2h",
		},
		&cli.Int64Flag{
			Name:  "changelog-max-lines",
			Usage: "max number of changelog entries to keep; 0 means unlimited",
		},
		&cli.IntFlag{
			Name:  "tier",
			Usage: "tier (0-3; 0 is default tier when unset)",
			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
			},
		},
	})
}

func configFlags() []cli.Flag {
	return []cli.Flag{
		&cli.BoolFlag{
			Name:    "yes",
			Aliases: []string{"y"},
			Usage:   "automatically answer 'yes' to all prompts and run non-interactively",
		},
		&cli.BoolFlag{
			Name:  "force",
			Usage: "skip sanity check and force update the configurations",
		},

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Pass a tier value in 0..3, e.g. `--tier 1`
2. Omit the flag entirely (unset means default tier 0)
3. Clamp computed tier values in your script to the 0-3 range

Example fix

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

tier = max(0, min(3, tier))
if tier < 0 || tier > 3 { die "tier must be 0-3" }

When it happens

Trigger: `juicefs config META --tier 4` (or negative), i.e. setting a cache tier outside the supported 0-3 range while the --tier flag is explicitly set.

Common situations: Typo or misunderstanding that tiers start at 0; scripting tier values computed elsewhere that exceed 3.

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

• --tier should be between 0 and 3
• --days should be at least 1
• 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/e5baa5c7d5c4a20c. Report an issue: GitHub.