%s references hidden param --%s; use a public canonical para

Error message

%s references hidden param --%s; use a public canonical param

What it means

Thrown when a conditional scope references a param that exists but is marked Hidden in its CLI flag metadata. Conditional scope requirements must be expressed with public canonical params so agents and users can see and satisfy them.

Source

Thrown at shortcuts/common/typed_compile_contract.go:76

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:
		return fmt.Errorf("Output.Mode %q is invalid", definition.Mode)
	}
	return nil

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Use the public canonical param that supersedes the hidden one
Expose the needed field as a public (non-hidden) input field if it is legitimately user-facing
Drop the conditional scope entry if the hidden param should not drive scope requirements

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

for _, p := range cs.Params {
  if f := fieldByName[p]; f.CLI.Hidden {
    return fmt.Errorf("conditional scope uses hidden param %q", p)
  }
}

Try / catch

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

Prevention

When marking a field Hidden, grep authorization blocks for its name
Reference only public canonical params in scope conditions
Document hidden fields as internal in the definition comments

When it happens

Trigger: ConditionalScopes.Params lists a declared but cli.Hidden input field.

Common situations: A field was made hidden (internal/deprecated) after the authorization block referenced it; referencing internal-only flags to express scope conditions; copies from older shortcut versions where the field was public.

Related errors

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