chocolatey/choco · error · ApplicationException

A packages.config file is only used with installs.

Error message

A packages.config file is only used with installs.

What it means

Thrown as an ApplicationException during UpgradeClean/Upgrade when any package name in config.PackageNames ends with '.config'. A packages.config file is a manifest listing multiple packages to install and is only valid for the install command — passing it to upgrade is an explicit error, not a supported workflow.

Source

Thrown at src/chocolatey/infrastructure.app/services/ChocolateyPackageService.cs:1145

        {
            ValidatePackageNames(config);

            this.Log().Info(@"Upgrading the following packages:");
            this.Log().Info(ChocolateyLoggers.Important, @"{0}".FormatWith(config.PackageNames));

            if (string.IsNullOrWhiteSpace(config.Sources))
            {
                this.Log().Error(ChocolateyLoggers.Important, @"Upgrading was NOT successful. There are no sources enabled for
 packages and none were passed as arguments.");
                Environment.ExitCode = 1;
                return new ConcurrentDictionary<string, PackageResult>();
            }

            this.Log().Info(@"By upgrading, you accept licenses for the packages.");

            foreach (var packageConfigFile in config.PackageNames.Split(new[] { ApplicationParameters.PackageNamesSeparator }, StringSplitOptions.RemoveEmptyEntries).OrEmpty().Where(p => p.EndsWith(".config")).ToList())
            {
                throw new ApplicationException("A packages.config file is only used with installs.");
            }

            var packageUpgrades = new ConcurrentDictionary<string, PackageResult>();

            try
            {
                GetInitialEnvironment(config, allowLogging: true);

                ConcurrentDictionary<string, PackageResult> results;

                if (config.SourceType.IsEqualTo(SourceTypes.Normal))
                {
                    var action = new Action<PackageResult, ChocolateyConfiguration>((packageResult, configuration) => HandlePackageResult(packageResult, configuration, CommandNameType.Upgrade));
                    var beforeUpgradeAction = new Action<PackageResult, ChocolateyConfiguration>((packageResult, configuration) => BeforeModifyAction(packageResult, configuration));

                    results = _nugetService.Upgrade(config, action, beforeUpgradeAction);
                }
                else

View on GitHub (pinned to 0d5abdd10c)

Solutions

1. Use 'choco install packages.config -y' instead of upgrade to install from a packages.config file.
2. To upgrade packages listed in a packages.config, first install them, then use 'choco upgrade all' or list individual package names.
3. Extract package names from the .config file and pass them individually: 'choco upgrade pkg1 pkg2 pkg3 -y'.

Example fix

// before: passing .config file to upgrade
choco upgrade packages.config -y

// after: use install for packages.config, upgrade for individual packages
choco install packages.config -y
choco upgrade pkg1 pkg2 pkg3 -y

// Before calling Upgrade, validate no package name ends with .config
var packageNames = config.PackageNames.Split(new[] { ApplicationParameters.PackageNamesSeparator }, StringSplitOptions.RemoveEmptyEntries);
if (packageNames.Any(p => p.EndsWith(".config", StringComparison.OrdinalIgnoreCase)))
{
    throw new InvalidOperationException("packages.config files cannot be used with upgrade. Use install instead.");
}

public static bool IsValidUpgradePackageName(string packageName)
{
    return !packageName.EndsWith(".config", StringComparison.OrdinalIgnoreCase);
}

try
{
    _packageService.Upgrade(config);
}
catch (ApplicationException ex) when (ex.Message.Contains("packages.config file is only used with installs"))
{
    logger.Error("Cannot upgrade from packages.config. Use 'choco install packages.config' first, then upgrade individual packages.");
}

When it happens

Trigger: Calling the Upgrade method (e.g., 'choco upgrade packages.config') where config.PackageNames contains a token ending in '.config'. The code splits PackageNames by the separator and throws immediately if any element matches the .config extension.

Common situations: A user attempts 'choco upgrade packages.config' thinking it will upgrade all packages listed in the config file. This is unsupported — packages.config is only recognized by 'choco install'. Also triggered when a package is literally named with a .config suffix.

Related errors

• When specifying the subcommand '{0}', you must also specify
• No rule with the name {0} could be found.
• A Rule Name (-n|--name) should not be specified when listing
• A Rule Name (-n|--name) is required when getting information
• When specifying the subcommand '{0}', you must also specify

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