parse policy yaml: 'rules:' is present but empty; remove the

Error message

parse policy yaml: 'rules:' is present but empty; remove the key, or list at least one rule

What it means

Parse distinguishes 'rules:' absent (nil pointer) from 'rules:' present but empty (non-nil, len 0) via a pointer field. An empty rules list would yield a single all-zero Rule that lets every annotated command through — a fail-open foot-gun — so Parse rejects it with explicit guidance.

Source

Thrown at internal/cmdpolicy/yaml/schema.go:121

	dec.KnownFields(true)
	if err := dec.Decode(&s); err != nil {
		return nil, fmt.Errorf("parse policy yaml: %w", err)
	}

	// Reject multi-document input: yaml.v3 only decodes one document
	// per call, so a stray "---" followed by another document would
	// silently drop the trailing rule.
	var extra fileSchema
	if err := dec.Decode(&extra); !errors.Is(err, io.EOF) {
		if err == nil {
			return nil, fmt.Errorf("parse policy yaml: multiple YAML documents are not allowed")
		}
		return nil, fmt.Errorf("parse policy yaml: %w", err)
	}

	if s.Rules != nil {
		if len(*s.Rules) == 0 {
			return nil, fmt.Errorf("parse policy yaml: 'rules:' is present but empty; remove the key, or list at least one rule")
		}
		if !s.ruleSchema.isZero() {
			return nil, fmt.Errorf("parse policy yaml: top-level rule fields cannot be combined with a 'rules:' list; move every rule under 'rules:'")
		}
		out := make([]*platform.Rule, 0, len(*s.Rules))
		for _, rs := range *s.Rules {
			out = append(out, rs.toRule())
		}
		return out, nil
	}

	// Backward-compatible single top-level rule (flat fields).
	return []*platform.Rule{s.ruleSchema.toRule()}, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add at least one rule entry under 'rules:'.
If no rules are intended, remove the 'rules:' key entirely (file then parses as a flat single rule).
Fix the generator/template to omit the key when the list is empty.

Example fix

// before
rules: []
// after
rules:
  - name: default
    allow: ["docs/*"]

Defensive patterns

Strategy: validation

Validate before calling

if bytes.Contains(data, []byte("rules:")) {
	// ensure at least one '- ' entry follows before handing to Parse
}

Try / catch

rules, err := yaml.Parse(data)
if err != nil && strings.Contains(err.Error(), "present but empty") {
	return fmt.Errorf("config generator produced an empty rules list; check upstream rule source: %w", err)
}

Prevention

Make generators omit 'rules:' when no rules exist.
Validate generated policy files in CI immediately after generation.
Never hand-empty a rules list; delete the key or replace with a real rule.

When it happens

Trigger: Calling Parse on YAML containing 'rules:' with no entries, e.g. 'rules: []' or a bare 'rules:' key with nothing under it.

Common situations: Config generators rendering an empty list when no rules are configured; manually emptying the rules list while keeping the key; templates whose loop produced zero items.

Related errors

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