PostMount modified Typed flag --%s or its input annotations

Error message

PostMount modified Typed flag --%s or its input annotations

What it means

Thrown by validateTypedPostMount when a flag declared during mount still exists after PostMount but differs from its declared definition — value type, default, usage text, shorthand, NoOptDefVal, deprecated status, hidden state, or flag annotations changed. Typed mounts treat the declared flag set (including input annotations) as an immutable contract, so PostMount may not alter it.

Source

Thrown at shortcuts/common/typed_mount_guard.go:99

		seen[name] = struct{}{}
		names = append(names, name)
	}
	for name := range after.flags {
		if _, ok := seen[name]; !ok {
			names = append(names, name)
		}
	}
	sort.Strings(names)
	for _, name := range names {
		beforeFlag, existedBefore := before.flags[name]
		afterFlag, existsAfter := after.flags[name]
		switch {
		case !existedBefore:
			return fmt.Errorf("PostMount added undeclared Typed flag --%s", name)
		case !existsAfter:
			return fmt.Errorf("PostMount removed Typed flag --%s", name)
		case !reflect.DeepEqual(beforeFlag, afterFlag):
			return fmt.Errorf("PostMount modified Typed flag --%s or its input annotations", name)
		}
	}
	return nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Move any flag metadata (usage, hidden, deprecated, annotations, shorthand) into the Typed flag declaration in the shortcut definition, not the PostMount hook.
If the flag needs a different default or type, change the declared Typed definition, not runtime state in PostMount.
Search the PostMount hook for calls like MarkHidden, MarkDeprecated, SetAnnotation, or direct Lookup(...).Field assignments and delete them.

Example fix

// before (PostMount hook)
func (h *hook) PostMount(cmd *cobra.Command) error {
    f := cmd.Flags().Lookup("chat_id")
    f.Usage = "custom usage" // modifies declared flag
    return nil
}
// after: declare it at mount time
flags: []command.Flag{{ Name: "chat_id", Usage: "custom usage", /* ... */ }}

Defensive patterns

Strategy: validation

Validate before calling

// Snapshot-compare in a unit test, mirroring the guard:
want := "Custom usage for chat"
cmd.SetArgs([]string{"--help"})
if f := cmd.Flags().Lookup("chat_id"); f == nil || f.Usage != want {
    t.Fatalf("declared flag chat_id changed; declare metadata at mount time")
}

Prevention

Never call MarkHidden, MarkDeprecated, SetAnnotation, or mutate Lookup results inside PostMount.
Review hooks with a checklist: no flag set mutation, no metadata writes.
Rely on mountDeclarative's guard tests; add dry-run E2E for every shortcut change so the guard runs in CI.

When it happens

Trigger: A PostMount hook calls flag.Usage = ..., cmd.Flags().Lookup(name).DefValue mutation, MarkHidden, MarkDeprecated, SetAnnotation, or changes Shorthand/NoOptDefVal on any Typed-declared flag.

Common situations: Developers customizing help output or hiding flags for internal commands in PostMount; changing usage strings centrally; or annotating flags with input metadata inside PostMount instead of declaring it in the Typed input definition.

Related errors

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