Function handleRootError

cmd/root.go:247–303

handleRootError dispatches a command error to the appropriate handler and returns the process exit code. Dispatch order: 1. Typed errors from errs/ (e.g. *errs.PermissionError, *errs.APIError, *errs.SecurityPolicyError, *errs.AuthenticationError, *errs.ConfigError): render via the typed envelope wr

(f *cmdutil.Factory, err error)

//     matching the explicit flag/subcommand guards. Flag parse errors are
//     already typed upstream by the root FlagErrorFunc.
func handleRootError(f *cmdutil.Factory, err error) int {
	errOut := f.IOStreams.ErrOut

	// When the typed error is a need_user_authorization signal, fold in the
	// current command's declared scopes as a Hint so the user/AI sees the
	// concrete scope(s) to re-auth with. The hint is computed on the fly from
	// local shortcut/service metadata — it never depends on server state.
	if !errs.IsRaw(err) {
		applyNeedAuthorizationHint(f, err)
	}

	// Staged dispatch: capture the typed exit code BEFORE attempting the
	// envelope write. WriteTypedErrorEnvelope is best-effort on the wire
	// (partial-write still returns true) so the exit code we read here is
	// preserved even if stderr is torn — torn stderr must not downgrade
	// typed exits 3/4/6/10 to the plain "Error:" path with exit 1.
	// WriteTypedErrorEnvelope still returns false when err carries no
	// Problem; in that case we fall through to the signal / plain-text paths.
	typedExit := output.ExitCodeOf(err)
	if output.WriteTypedErrorEnvelope(errOut, err, string(f.ResolvedIdentity)) {
		return typedExit
	}

	// Partial-failure (batch / multi-status): the ok:false result envelope is
	// already on stdout; set the exit code and write nothing to stderr.
	var pfErr *output.PartialFailureError
	if errors.As(err, &pfErr) {
		return pfErr.Code
	}

	// Silent-exit signal (e.g. `auth check` predicate, or `update --json`):
	// stdout already carries the result; honor the requested exit code and
	// write nothing to stderr.
	var bareErr *output.BareError
	if errors.As(err, &bareErr) {
		return bareErr.Code
	}

	// Errors reaching here are untyped: every RunE returns a typed errs.* error
	// and flag-parse errors are typed by the root FlagErrorFunc. The remainder
	// is either a cobra usage mistake (missing required flag, unknown command,
	// wrong arg count), which cobra surfaces as a plain error identified by its
	// stable text — the same external contract unknownFlagName relies on — or an
	// untyped error that leaked past the typed boundary. Classify the former as
	// invalid_argument (exit 2, like the explicit guards); treat the latter as an
	// internal fault (exit 5) rather than blaming the user's input. The message
	// is preserved either way, and the typed envelope still carries any pending
	// deprecation notice.
	var fallback error
	if isCobraUsageError(err) {
		fallback = errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err.Error())
	} else {
		fallback = errs.NewInternalError(errs.SubtypeUnknown, "%s", err.Error()).WithCause(err)
	}
	output.WriteTypedErrorEnvelope(errOut, fallback, string(f.ResolvedIdentity))
	return output.ExitCodeOf(fallback)
}