What causes "%s references unknown param --%s" in larksuite/cli?

Correct the param name to match a declared input field

%s references unknown param --%s

Error message

%s references unknown param --%s

What it means

Thrown when a conditional scope in Authorization.<identity>.ConditionalScopes references a param name that is not among the compiled input fields. Like the Relations check, this guarantees scope conditions only mention flags the shortcut actually accepts.

Source

Thrown at shortcuts/common/typed_compile_contract.go:73

	}
	return result, nil
}

func compileAuthorization(definition typedAuthorizationDefinition, fields []compiledInputField, fieldByName map[string]int) error {
	for identity, authorization := range definition.Identities {
		for i, conditional := range authorization.ConditionalScopes {
			path := fmt.Sprintf("Authorization.%s.ConditionalScopes[%d]", identity, i)
			if len(conditional.Params) > 0 && conditional.When == "" {
				return fmt.Errorf("%s.Params requires agent-readable When text", path)
			}
			seen := make(map[string]struct{}, len(conditional.Params))
			for j, param := range conditional.Params {
				if param == "" || param != strings.TrimSpace(param) {
					return fmt.Errorf("%s.Params[%d] must be a non-blank trimmed param", path, j)
				}
				fieldIndex, ok := fieldByName[param]
				if !ok {
					return fmt.Errorf("%s references unknown param --%s", path, param)
				}
				if fields[fieldIndex].cli.Hidden {
					return fmt.Errorf("%s references hidden param --%s; use a public canonical param", path, param)
				}
				if _, duplicate := seen[param]; duplicate {
					return fmt.Errorf("%s.Params contains duplicate param --%s", path, param)
				}
				seen[param] = struct{}{}
			}
		}
	}
	return nil
}

func validateOutput(definition typedOutputDefinition, dataShape typedValueShape) error {
	switch definition.Mode {
	case typedOutputGeneric, typedOutputFixedJSON:
	default:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Correct the param name to match a declared input field
Add the missing field to the input definition if it is genuinely needed
Delete the stale param from ConditionalScopes.Params

Example fix

// before
ConditionalScopes: []ConditionalScope{{Params: []string{"--file-token"}, When: "..."}}
// input declares --file_token
// after
ConditionalScopes: []ConditionalScope{{Params: []string{"--file_token"}, When: "..."}}

Defensive patterns

Strategy: validation

Validate before calling

for _, p := range cs.Params {
  if _, ok := fieldNames[p]; !ok {
    return fmt.Errorf("conditional scope references undeclared param %q", p)
  }
}

Try / catch

if err := common.CompileTypedDefinition(def); err != nil {
  return fmt.Errorf("conditional scope unknown param: %w", err)
}

Prevention

Update ConditionalScopes.Params whenever input fields are renamed/removed
Derive scope params from a shared constants file with the input fields
Add a compile-all-definitions test

When it happens

Trigger: ConditionalScopes.Params lists a flag (e.g. "--folder-token") that the input definition does not declare.

Common situations: Renaming or removing an input field without updating the authorization block; copying conditional scopes from another shortcut with different params; typo in the param name.

Related errors

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