chocolatey/choco · error · OptionException

Cannot bundle unregistered option '{0}'.

Error message

Cannot bundle unregistered option '{0}'.

What it means

Thrown by Mono.Options' bundle parser when a clustered short-option string (e.g. -abc) contains a character that is not a registered option. Bundling is only allowed when every character in the cluster maps to a known option; the first unregistered character (after at least one valid one) triggers this OptionException naming the offending -x token.

Source

Thrown at src/chocolatey/infrastructure/commandline/Options.cs:896

			}
			return false;
		}

        private bool ParseBundledValue(string f, string n, OptionContext c)
        {
            IDictionary<Option, string> normalOptions = new Dictionary<Option, string>();
            if (f != "-")
                return false;
            for (int i = 0; i < n.Length; ++i)
            {
                Option p;
                string opt = f + n[i].ToString();
                string rn = n[i].ToString();
                if (!Contains(rn))
                {
                    if (i == 0)
                        return false;
                    throw new OptionException(string.Format(_localizer(
                                    "Cannot bundle unregistered option '{0}'."), opt), opt);
                }
                p = this[rn];

                switch (p.OptionValueType)
                {
                    case OptionValueType.None:
                        normalOptions.Add(p, opt);
                        break;
                    case OptionValueType.Optional:
                    case OptionValueType.Required:
                        {
                            string v = n.Substring(i + 1);
                            c.Option = p;
                            c.OptionName = opt;
                            ParseValue(v.Length != 0 ? v : null, c);
                            return true;
                        }

View on GitHub (pinned to 0d5abdd10c)

Solutions

1. Split the cluster into individual flags and run `choco <command> -h` to confirm each short flag is registered for that command.
2. Remove the unregistered character from the cluster, or replace it with the correct flag name.
3. Prefer long-form flags (--verbose) in scripts for resilience against short-flag renames.

Example fix

// before (x not registered)
choco search -vx query

// after
choco search -v query

// Validate each character in a bundled short-options cluster against registered options.
string cluster = "-vx";
var registered = new HashSet<string>(new[] { "v" }); // known short names for the command
foreach (char ch in cluster.Substring(1))
    if (!registered.Contains(ch.ToString()))
        throw new ArgumentException("Unregistered short option '-" + ch + "' in cluster '" + cluster + "'.");

try
{
    optionSet.Parse(args);
}
catch (OptionException ex) when (ex.Message.Contains("Cannot bundle unregistered option"))
{
    Console.Error.WriteLine(ex.Message);
    Console.Error.WriteLine("Run choco <command> -h to list valid short flags.");
    Environment.Exit(1);
}

When it happens

Trigger: Passing something like -vxy where -v is valid but -x/-y are not registered, and the parser is in bundling mode (input starts with a lone -). The i == 0 early-return means a wholly-unregistered cluster returns false (treated as a value) rather than throwing, so the throw only happens for a mixed cluster.

Common situations: Typos in combined flags, or assuming a flag exists that belongs to a different Chocolatey command. Version upgrades that renamed or removed a short flag leave scripts with stale clusters.

Related errors

• Missing required value for option '{0}'.
• Could not convert string `{0}' to type {1} for option `{2}'.
• Error: Found {0} option values when expecting {1}.
• A value was passed to the `-v` option, but this option does

AI-assisted analysis of chocolatey/choco@0d5abdd10c (2026-08-13). Data as JSON: /api/errors/4883f9356e454eb7. Report an issue: GitHub.