{"record":{"id":"2842755317519c31","repo":"vxcontrol/pentagi","slug":"invalid-usagestatsperiod-s","errorCode":null,"errorMessage":"invalid UsageStatsPeriod: %s","messagePattern":"invalid UsageStatsPeriod: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/server/models/analytics.go","lineNumber":31,"sourceCode":"const (\n\tUsageStatsPeriodWeek    UsageStatsPeriod = \"week\"\n\tUsageStatsPeriodMonth   UsageStatsPeriod = \"month\"\n\tUsageStatsPeriodQuarter UsageStatsPeriod = \"quarter\"\n)\n\nfunc (p UsageStatsPeriod) String() string {\n\treturn string(p)\n}\n\n// Valid is function to control input/output data\nfunc (p UsageStatsPeriod) Valid() error {\n\tswitch p {\n\tcase UsageStatsPeriodWeek,\n\t\tUsageStatsPeriodMonth,\n\t\tUsageStatsPeriodQuarter:\n\t\treturn nil\n\tdefault:\n\t\treturn fmt.Errorf(\"invalid UsageStatsPeriod: %s\", p)\n\t}\n}\n\n// Validate is function to use callback to control input/output data\nfunc (p UsageStatsPeriod) Validate(db *gorm.DB) {\n\tif err := p.Valid(); err != nil {\n\t\tdb.AddError(err)\n\t}\n}\n\n// ==================== Basic Statistics Structures ====================\n\n// UsageStats represents token usage statistics\n// nolint:lll\ntype UsageStats struct {\n\tTotalUsageIn       int     `json:\"total_usage_in\" validate:\"min=0\"`\n\tTotalUsageOut      int     `json:\"total_usage_out\" validate:\"min=0\"`\n\tTotalUsageCacheIn  int     `json:\"total_usage_cache_in\" validate:\"min=0\"`","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/server/models/analytics.go#L13-L49","documentation":"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.","triggerScenarios":"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\").","commonSituations":"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.","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."],"exampleFix":"// before\n{\"period\": \"30d\"}\n// after\n{\"period\": \"month\"}","handlingStrategy":"validation","validationCode":"const USAGE_STATS_PERIODS = [\"week\", \"month\", \"quarter\"] as const;\ntype UsageStatsPeriod = typeof USAGE_STATS_PERIODS[number];\nfunction isValidPeriod(p: string): p is UsageStatsPeriod {\n  return (USAGE_STATS_PERIODS as readonly string[]).includes(p);\n}\nif (!isValidPeriod(input.period)) throw new Error(`invalid UsageStatsPeriod: ${input.period}`);","typeGuard":"function isUsageStatsPeriod(v: unknown): v is \"week\" | \"month\" | \"quarter\" {\n  return v === \"week\" || v === \"month\" || v === \"quarter\";\n}","tryCatchPattern":"try {\n  await api.getUsageStats({ period });\n} catch (err) {\n  if (String(err).includes(\"invalid UsageStatsPeriod\")) {\n    await api.getUsageStats({ period: \"month\" }); // fallback to a known-good period\n  } else throw err;\n}","preventionTips":["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."],"tags":["validation","enum","gorm","rest"],"backgroundTag":"invalid-enum-value","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}