larksuite/cli · error

%svalue does not match any of oneOf alternatives

Error message

%svalue does not match any of oneOf alternatives

What it means

oneOf validation error from collectSchemaErrors: the value matched none of the schema's `oneOf` alternatives. The validator probes each alternative and only reports this when every probe produced errors, so the actual per-alternative failures are suppressed in favor of a single aggregate message. Wrapped into a typed flag validation error with a --print-schema hint.

Source

Thrown at shortcuts/sheets/flag_schema_validate.go:421

			if hint := suggestEnumForError(value, schema.Enum); hint != "" {
				msg += fmt.Sprintf(` (did you mean %q?)`, hint)
			}
			c.add(fmt.Errorf("%s", msg)) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
	}

	if len(schema.OneOf) > 0 {
		matched := false
		for _, sub := range schema.OneOf {
			probe := &schemaErrorCollector{}
			collectSchemaErrors(value, sub, path, probe)
			if len(probe.errs) == 0 {
				matched = true
				break
			}
		}
		if !matched {
			c.add(fmt.Errorf("%svalue does not match any of oneOf alternatives", pathPrefix(path))) //nolint:forbidigo // intermediate error; validateFlagAgainstSchema wraps it into a typed flag validation error with a --print-schema hint
		}
	}

	// Object-level checks. `required` and `properties` are independent
	// per JSON Schema: `required` enforces keys regardless of whether
	// the schema also describes their per-key shape via `properties`.
	if obj, ok := value.(map[string]interface{}); ok {
		for _, key := range schema.Required {
			if c.full() {
				return
			}
			if _, present := obj[key]; !present {
				msg := fmt.Sprintf("required property %q is missing at %s", key, pathOrRoot(path))
				// Inline the missing field's type / one-line description / enum so
				// the agent supplies a correctly-shaped value on the first retry
				// instead of fetching the full schema.
				if hint := schemaFieldHint(schema.Properties[key]); hint != "" {
					msg += "; expected " + hint

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Run --print-schema and pick exactly one oneOf alternative; supply all of its required fields and none of the other branch's fields.
2. Compare your payload against each alternative's required/properties set field by field.
3. If fields from multiple branches were merged, split the payload to conform to a single branch.

Example fix

// before
--data '{"cell": 1, "value": "x"}'  // mixes two alternatives
// after
--data '{"cell": {"text": "x"}}'  // single valid alternative

// ensure the payload matches exactly one oneOf branch
function matchesBranch(obj, requiredKeys) {
  return requiredKeys.every(k => k in obj);
}
if (!matchesBranch(data, ["cell"]) && !matchesBranch(data, ["value"])) {
  throw new Error("payload matches no oneOf alternative");
}

function isCellPayload(v: unknown): v is { cell: object } {
  return typeof v === "object" && v !== null && "cell" in v && Object.keys(v).every(k => ["cell"].includes(k));
}

try {
  runCommand(args);
} catch (e) {
  if (e.message.includes("oneOf")) {
    // fetch full schema via --print-schema and rebuild payload for one branch
  }
}

When it happens

Trigger: Passing a value whose shape matches no oneOf branch, e.g. a polymorphic cell/row payload that is neither the `{cell:{...}}` form nor the `{value:{...}}` form defined by the schema.

Common situations: Mixing fields from two different alternatives into one object; missing a required discriminator key; passing a scalar where all alternatives expect an object.

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

• %s does not match any allowed shape
• %svalue %v is below minimum %v
• %svalue %v is above maximum %v
• %sarray has %d items, minimum is %d
• %sarray has %d items, maximum is %d

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