What causes "invalid UsageStatsPeriod: %s" in vxcontrol/pentagi?

Set the period to one of the accepted values: week, month, or quarter (match the exact constant string).

invalid UsageStatsPeriod: %s

Error message

invalid UsageStatsPeriod: %s

What it means

UsageStatsPeriod.Valid() in backend/pkg/server/models/analytics.go rejects any period string other than the defined constants (week, month, quarter). It is invoked by the GORM Validate callback, so an invalid period on a request body or DB-bound struct aborts the operation with this error.

Source

Thrown at backend/pkg/server/models/analytics.go:31

const (
	UsageStatsPeriodWeek    UsageStatsPeriod = "week"
	UsageStatsPeriodMonth   UsageStatsPeriod = "month"
	UsageStatsPeriodQuarter UsageStatsPeriod = "quarter"
)

func (p UsageStatsPeriod) String() string {
	return string(p)
}

// Valid is function to control input/output data
func (p UsageStatsPeriod) Valid() error {
	switch p {
	case UsageStatsPeriodWeek,
		UsageStatsPeriodMonth,
		UsageStatsPeriodQuarter:
		return nil
	default:
		return fmt.Errorf("invalid UsageStatsPeriod: %s", p)
	}
}

// Validate is function to use callback to control input/output data
func (p UsageStatsPeriod) Validate(db *gorm.DB) {
	if err := p.Valid(); err != nil {
		db.AddError(err)
	}
}

// ==================== Basic Statistics Structures ====================

// UsageStats represents token usage statistics
// nolint:lll
type UsageStats struct {
	TotalUsageIn       int     `json:"total_usage_in" validate:"min=0"`
	TotalUsageOut      int     `json:"total_usage_out" validate:"min=0"`
	TotalUsageCacheIn  int     `json:"total_usage_cache_in" validate:"min=0"`

View on GitHub (pinned to ea665308ba)

Solutions

Set the period to one of the accepted values: week, month, or quarter (match the exact constant string).
Check the request payload/query param spelling and casing against the Go constants in analytics.go.
If you need a different range, aggregate client-side from the supported periods instead of inventing a new one.
Update the client SDK/frontend schema if it still offers a stale period option.

Example fix

// before
{"period": "30d"}
// after
{"period": "month"}

Defensive patterns

Strategy: validation

Validate before calling

const USAGE_STATS_PERIODS = ["week", "month", "quarter"] as const;
type UsageStatsPeriod = typeof USAGE_STATS_PERIODS[number];
function isValidPeriod(p: string): p is UsageStatsPeriod {
  return (USAGE_STATS_PERIODS as readonly string[]).includes(p);
}
if (!isValidPeriod(input.period)) throw new Error(`invalid UsageStatsPeriod: ${input.period}`);

Type guard

function isUsageStatsPeriod(v: unknown): v is "week" | "month" | "quarter" {
  return v === "week" || v === "month" || v === "quarter";
}

Try / catch

try {
  await api.getUsageStats({ period });
} catch (err) {
  if (String(err).includes("invalid UsageStatsPeriod")) {
    await api.getUsageStats({ period: "month" }); // fallback to a known-good period
  } else throw err;
}

Prevention

Derive the period picker options from the same constants the backend uses; never free-text the field.
Add a zod/JSON-schema enum validation on the client before the request.
Copy exact constant strings from models/analytics.go when writing scripts.
Write a unit test asserting only week/month/quarter pass your client validator.

When it happens

Trigger: POST/GET analytics or usage-stats endpoints with a period field that is not exactly one of the accepted constants (e.g. "year", "Weekly", "", "30d").

Common situations: Typo or wrong casing in a dashboard query parameter; a client hardcoding "year" or "30d" assuming more granularities exist; an API version mismatch where an older client sends a since-removed period value.

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

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/2842755317519c31. Report an issue: GitHub.