larksuite/cli · error

schema contains blank or untrimmed token %q

Error message

schema contains blank or untrimmed token %q

What it means

Thrown by parseSchemaTag when a semicolon-separated schema token is empty or has leading/trailing whitespace. The parser enforces strict, well-trimmed token grammar so tags remain canonical and diffable.

Source

Thrown at shortcuts/common/typed_compile_args.go:405

	minimum      *float64
	maximum      *float64
	minItems     *int
	maxItems     *int
}

func schemaHasShapeConstraints(schema schemaTag) bool {
	return len(schema.enum) > 0 || schema.format != "" || hasStringConstraints(schema) || hasNumberConstraints(schema) || hasItemConstraints(schema)
}

func parseSchemaTag(raw string, valueType reflect.Type, input bool) (schemaTag, error) {
	var result schemaTag
	if raw == "" {
		return result, fmt.Errorf("schema tag must declare exactly one of required or optional")
	}
	seen := make(map[string]struct{})
	for _, token := range strings.Split(raw, ";") {
		if token == "" || token != strings.TrimSpace(token) {
			return result, fmt.Errorf("schema contains blank or untrimmed token %q", token)
		}
		key, value, hasValue := strings.Cut(token, "=")
		if _, duplicate := seen[key]; duplicate {
			return result, fmt.Errorf("schema token %q is duplicated", key)
		}
		seen[key] = struct{}{}
		switch key {
		case "required":
			if hasValue {
				return result, fmt.Errorf("schema token required does not accept a value")
			}
			result.required = true
		case "optional":
			if hasValue {
				return result, fmt.Errorf("schema token optional does not accept a value")
			}
			result.optional = true
		case "nullable", "nonnullable":

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove trailing/leading semicolons and extra whitespace between tokens
2. Write tokens as `key=value` pairs separated by plain `;` with no spaces
3. Reformat the tag onto one clean line

Example fix

// before
Name string `cli:"--name;schema:\"required; enum=a, b\""`
// after
Name string `cli:"--name;schema:\"required;enum=a,b\""`

for _, tok := range strings.Split(tag, ";") {
    if tok == "" || tok != strings.TrimSpace(tok) {
        return fmt.Errorf("blank or untrimmed schema token %q", tok)
    }
}

When it happens

Trigger: Tags like `schema:"required;"` (trailing semicolon -> empty token), `"required; enum=a"` (space after semicolon), or `" required"` (leading space); any token where token != strings.TrimSpace(token) or token == "".

Common situations: Multi-token tags wrapped across source lines with stray spaces; gofmt-less hand edits leaving dangling semicolons; copy-paste from docs introducing spaces around separators.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• schema tag must declare exactly one of required or optional
• schema token %q is duplicated
• schema token required does not accept a value
• schema token optional does not accept a value
• schema token %s does not accept a value

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/00a1272405f37725. Report an issue: GitHub.