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

Correct the param name to match a declared input field

references unknown param

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.

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.

Appendix: 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)