larksuite/cli · error
unknown schema token %q
Error message
unknown schema token %q
What it means
parseSchemaTag only accepts a fixed set of schema tag keys (required, optional, nullable, nonnullable, default, enum, format, minLength, maxLength, minimum, maximum, minItems, maxItems). Any other key in the semicolon-separated tag triggers this error, which is a compile-time guard against silently ignoring misspelled constraints.
Source
Thrown at shortcuts/common/typed_compile_args.go:491
v, err := parseFiniteFloat(value)
if err != nil {
return result, fmt.Errorf("schema maximum: %w", err)
}
result.maximum = &v
case "minItems":
v, err := parseNonnegativeInt(value)
if err != nil {
return result, fmt.Errorf("schema minItems: %w", err)
}
result.minItems = &v
case "maxItems":
v, err := parseNonnegativeInt(value)
if err != nil {
return result, fmt.Errorf("schema maxItems: %w", err)
}
result.maxItems = &v
default:
return result, fmt.Errorf("unknown schema token %q", key)
}
}
if result.required == result.optional {
return result, fmt.Errorf("schema must declare exactly one of required or optional")
}
if result.required && result.defaultValue.Set {
return result, fmt.Errorf("required input cannot declare default")
}
if result.nullable != nil && *result.nullable && !isNilCapable(valueType) {
return result, fmt.Errorf("nullable requires a nil-capable Go type")
}
if result.minLength != nil && result.maxLength != nil && *result.minLength > *result.maxLength {
return result, fmt.Errorf("minLength exceeds maxLength")
}
if result.minimum != nil && result.maximum != nil && *result.minimum > *result.maximum {
return result, fmt.Errorf("minimum exceeds maximum")
}
if result.minItems != nil && result.maxItems != nil && *result.minItems > *result.maxItems {View on GitHub (pinned to 7fd6ef3c07)
Solutions
- Check the spelling against the supported token list and fix the key name.
- Remove tokens that have no equivalent in this library.
- Consult the shortcut typed-input docs for the exact supported tag grammar.
Example fix
// before Name string `schema:"required;minLenght=3"` // after Name string `schema:"required;minLength=3"`
Defensive patterns
Strategy: validation
Validate before calling
var schemaKeys = map[string]bool{"required": true, "optional": true, "nullable": true, "nonnullable": true, "default": true, "enum": true, "format": true, "minLength": true, "maxLength": true, "minimum": true, "maximum": true, "minItems": true, "maxItems": true}
func tokensKnown(tag string) bool {
for _, tok := range strings.Split(tag, ";") {
k, _, _ := strings.Cut(tok, "=")
if !schemaKeys[k] {
return false
}
}
return true
} Prevention
- Copy token names from an existing valid schema tag instead of typing them.
- Watch for camelCase: minLength/maxLength/minItems/maxItems, minimum/maximum.
- Add a compile-time test over all input structs so unknown tokens fail CI.
When it happens
Trigger: A tag containing an unrecognized key, e.g. schema:"required;minLenght=3" (typo) or schema:"required;unique=true".
Common situations: Misspelled token names (minLength/minLenght, nullable/nulable), tokens invented by analogy with JSON Schema, or tags copied from a different library with a different tag grammar.
Related errors
- schema minItems: %w
- schema maxItems: %w
- schema must declare exactly one of required or optional
- required input cannot declare default
- nullable requires a nil-capable Go type
AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04).
Data as JSON: /api/errors/aa2f93d289e20581.
Report an issue: GitHub.