juicedata/juicefs · error

invalid tier id: %d

Error message

invalid tier id: %d

What it means

In azure.go Copy(), when a tier id is present in the context (TierKey) and src == dst, the code looks the id up in b.tiers. This error is returned when the id is not present in the configured tiers map at all, so the requested tier operation cannot be resolved to any configured storage class.

Source

Thrown at pkg/object/azure.go:150

		blobClient := b.azblobCli.ServiceClient().NewContainerClient(b.cName).NewBlobClient(src)
		if t, ok := b.tiers[id]; ok {
			tier := str2Tier(t.Sc)
			if tier == nil {
				return fmt.Errorf("tierID:%d not found for %s", id, src)
			}
			if _, err := blobClient.SetTier(ctx, *tier, &blob2.SetTierOptions{}); err != nil {
				return err
			}
			if t.Tag != "" && ValidateTag(t.Tag) {
				parts := strings.SplitN(t.Tag, "=", 2)
				if len(parts) == 2 {
					if _, err := blobClient.SetTags(ctx, map[string]string{parts[0]: parts[1]}, nil); err != nil {
						return err
					}
				}
			}
		} else {
			return fmt.Errorf("invalid tier id: %d", id)
		}
		return nil
	}
	dstCli := b.container.NewBlobClient(dst)
	srcCli := b.container.NewBlobClient(src)
	options := &blob2.CopyFromURLOptions{}
	if b.tiers[0].Sc != "" {
		options.Tier = str2Tier(b.tiers[0].Sc)
	}

	var srcURL string
	var err error

	if b.useTokenAuth {
		// Token-based authentication: use direct blob URL
		// Azure will authenticate using the OAuth token from the credential chain
		srcURL = srcCli.URL()
		logger.Debugf("Using token-based authentication for Copy operation (direct URL without SAS)")

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Ensure the tier id used by the client exists in the backend's tiers configuration (ids are indexes into the tiers list)
2. Re-check the volume's tier configuration (`juicefs config <meta-url>`) and add the missing tier entry
3. Align client-side storage-class values with the configured tier count (valid ids are 0..len(tiers)-1)
4. Remove the tier request if tiering is not configured for this volume

Example fix

// before: request tier 2 with only 2 tiers configured (ids 0,1)
ctx = context.WithValue(ctx, TierKey{}, uint8(2))
// after
ctx = context.WithValue(ctx, TierKey{}, uint8(1))

tierID := uint8(2); if int(tierID) >= len(cfg.Tiers) { /* reject: tier id out of range */ }

When it happens

Trigger: Calling Copy (or a write path that sets the tier) with a tier id larger than the configured tiers list, or before any tiers were configured for the Azure backend.

Common situations: Client sending --writeback/storage-class tier ids that exceed the number of tiers defined at format time; tiers config omitted while tiered writes are still requested; index off-by-one between writer and configured tiers.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• tierID:%d not found for %s
• Invalid endpoint: %v, error: %v
• invalid hour number
• invalid unit
• cannot disable dir stats when there are still %d dir quotas:

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