larksuite/cli · error

Input.Relations[%d] references unknown param --%s

Error message

Input.Relations[%d] references unknown param --%s

What it means

This error is thrown at shortcut-definition compile time when a relation declared in Input.Relations lists a param name (--flag) that does not exist among the compiled input fields. The compiler looks each relation param up in fieldByName and fails fast so invalid shortcut definitions never reach runtime. It is a definition-contract violation, not a runtime user error.

Source

Thrown at shortcuts/common/typed_compile_contract.go:40

			exact = 2
		default:
			return nil, fmt.Errorf("Input.Relations[%d].Kind %q is invalid", i, definition.Kind)
		}
		if exact > 0 && len(definition.Params) != exact || exact == 0 && len(definition.Params) < minimum {
			return nil, fmt.Errorf("Input.Relations[%d] kind %s has invalid param count %d", i, definition.Kind, len(definition.Params))
		}
		if definition.Presence != typedPresenceExplicit && definition.Presence != typedPresenceNonZero {
			return nil, fmt.Errorf("Input.Relations[%d].Presence %q is invalid", i, definition.Presence)
		}
		if definition.Stage != typedStageSourcePreRun && definition.Stage != typedStageAfterPrepare {
			return nil, fmt.Errorf("Input.Relations[%d].Stage %q is invalid", i, definition.Stage)
		}
		compiled := compiledRelation{kind: definition.Kind, presence: definition.Presence, stage: definition.Stage}
		local := make(map[string]struct{})
		for _, name := range definition.Params {
			field, ok := fieldByName[name]
			if !ok {
				return nil, fmt.Errorf("Input.Relations[%d] references unknown param --%s", i, name)
			}
			if _, duplicate := local[name]; duplicate {
				return nil, fmt.Errorf("Input.Relations[%d] repeats param --%s", i, name)
			}
			local[name] = struct{}{}
			compiled.fields = append(compiled.fields, field)
		}
		keyBytes, _ := json.Marshal(definition)
		key := string(keyBytes)
		if _, duplicate := seen[key]; duplicate {
			return nil, fmt.Errorf("Input.Relations[%d] duplicates an earlier relation", i)
		}
		seen[key] = struct{}{}
		result = append(result, compiled)
	}
	return result, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

  1. Add the referenced param as a declared input field in the same typed definition
  2. Fix the typo / casing in the relation's Params entry to match an existing field name
  3. Remove the stale param from the relation if the field no longer exists

Example fix

// before
Relations: []Relation{{Kind: "lookup", Params: []string{"--chat-id"}}}
// (input fields only declare --chat_id)
// after
Relations: []Relation{{Kind: "lookup", Params: []string{"--chat_id"}}}
Defensive patterns

Strategy: validation

Validate before calling

for _, rel := range def.Input.Relations {
  for _, name := range rel.Params {
    if _, ok := fieldNames[name]; !ok {
      return fmt.Errorf("relation references undeclared param %q", name)
    }
  }
}

Try / catch

if err := common.CompileTypedDefinition(def); err != nil {
  var cerr *common.CompileError
  if errors.As(err, &cerr) { log.Fatalf("invalid definition: %v", err) }
  return err
}

Prevention

When it happens

Trigger: Registering a shortcut whose typedDefinition has a Relation with Params containing a flag name that is not declared as an input field (typo, removed field, or casing mismatch).

Common situations: A field was renamed or deleted from the input struct but the relation still lists the old name; copy-pasting a relation from another shortcut whose params differ; adding a relation before adding the corresponding field.

Related errors

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