There are some well-known things you may run into when you are using Chocolatey. We've tried to get some of the high level things you may run into into one document.

NOTE: This is a work in progress. It doesn't cover all of the troubleshooting steps that are known but it is attempting to cover quite a few.


If you are unable to find answers to your questions here, please see (FOSS and Licensed) and to learn more about how you can report issues and get things fixed if they are broken.

Also consider the frequently asked questions.

Chocolatey Installation

The underlying connection was closed

If you see an error that looks similar to the following:

Exception calling "DownloadString" with "1" argument(s): "The underlying connection was closed: An unexpected error
occurred on a receive."
At line:1 char:1
+ iex ((New-Object System.Net.WebClient).DownloadString(' ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [], MethodInvocationException
    + FullyQualifiedErrorId : WebException

It's possible that you are attempting to install from a server that needs to use TLS 1.1 or TLS 1.2.

Please see Installing with Restricted TLS

I'm getting a 403 unauthorized issue attempting to install Chocolatey

Please see I'm getting a 403 unauthorized issue when attempting to use the community package repository.

I am having trouble with PowerShell to install Chocolatey

See the More Options section of installation.

Licensed Installation and Issues

See licensed installation. If you are having issues, please see for details on how to get support.

Creating Packages

Install-ChocolateyPath doesn't seem to work.

I added Install-ChocolateyPath $binPath, but after installing when I try to run the installed application I get "not recognized as the name of a cmdlet, function, script file, or operable program." Please see My PATH is not getting updated.

ERROR: Cannot bind parameter because parameter 'fileType' is specified more than once.

This error is seen sometimes on versions of Chocolatey older than 0.10.6. The problem is likely you have the following in your packaging:

$toolsPath      = $(Split-Path -parent $MyInvocation.MyCommand.Definition)

$packageArgs = @{
  packageName   = 'test'
  fileType      = 'MSI'
  file          = "$toolsPath\somefile.msi"
  softwareName  = 'test'
  silentArgs    = '/qn /norestart'
  validExitCodes= @(0)

Install-ChocolateyPackage @packageArgs
#Install-ChocolateyInstallPackage @packageArgs # this is what you meant to use in this case.

Install-ChocolateyPackage didn't have both a File parameter and a FileType parameter. PowerShell has a "feature" where it does partial matching of parameters. When you splat the parameters in, it tries to apply both File and FileType to FileType and throws the above error.

Typically, when you are installing locally, you likely want to use Install-ChocolateyInstallPackage anyway.

Reference: (you will need to join the group to see the message)

ERROR: This package does not support 64 bit architecture.

This message is from - it is when the url value chosen is empty. This is common when you are creating a package and you forget to use splatting, instead passing the variable in as the first positional parameter to a function.

This means you have set up your arguments for a function and then called something like Install-ChocolateyPackage $packageArgs instead of Install-ChocolateyPackage @packageArgs. Note @ is for splatting, taking the values in the hash variable and using the key/values to pass those each as parameters to a function, where $ just passes the entire hash as the first parameter of the function.

# this is a hash array
$packageArgs = @{
  packageName   = 'test'
  fileType      = 'exe'
  url           = 'https://location'
  url64bit      = 'https://location64'
  checksum      = 'checksum'
  checksum64    = 'checksum64'
  checksumType  = 'sha256'
  silentArgs    = "/qn /norestart /l*v `"$($env:TEMP)\$($packageName).$($env:chocolateyPackageVersion).MsiInstall.log`""
  validExitCodes= @(0, 3010, 1641)

Install-ChocolateyPackage $packageArgs # this is incorrect and will pass the entire hash as the first positional parameter
#Install-ChocolateyPackage @packageArgs # is what you are looking for

# Splatting takes the above hash and calls Install-ChocolateyPackage like this:
# Install-ChocolateyPackage -PackageName 'test' -FileType 'exe' -Url 'https://location' `
#           -Url64bit 'https://location64' -Checksum 'checksum' -Checksum64 'checksum64' `
#           -ChecksumType 'sha256' `
#           -SilentArgs "/qn /norestart /l*v `"$($env:TEMP)\$($packageName).$($env:chocolateyPackageVersion).MsiInstall.log`"" `
#           -ValidExitCodes @(0, 3010, 1641)

NOTE: It is helpful to always use choco new when creating packages, it has this correct and you never run into this error.


"ERROR: This package does not support 64 bit architecture." when trying to install from a local or included binary.

This is similar to the above, the error is the same. In most cases it stems from setting up your package parameters for Install-ChocolateyInstallPackage but calling Install-ChocolateyPackage instead. Learn the differences at the PowerShell function reference.

Reference: (you will need to join the group to see the message)

My package can't find dependencies

Please see unable to resolve dependency.

ERROR: A null key is not allowed in a hash literal.

Typically you see this if you accidentally use a variable name on the left side of a hash:

$packageArgs = @{
  packageName   = $env:ChocolateyPackageName
  $file         = $fileLocation

Note the use of $file on the left side, which should be just file. Once you fix that, things should start working appropriately.


I can't get the PowerShell tab completion working.

See next question.

Why does choco in{tab} not work for me?

This means the import failed during install/upgrade. Chocolatey does supply a warning when this happens in the install/upgrade log. Take a look there.

The warning may look like: "Not setting tab completion: Profile file does not exist at 'C:\Users\garyc\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1'."

Once you've looked at your log to determine what it said, here are some followup steps:

# Chocolatey profile
$ChocolateyProfile = "$env:ChocolateyInstall\helpers\chocolateyProfile.psm1"
if (Test-Path($ChocolateyProfile)) {
  Import-Module "$ChocolateyProfile"

Microsoft.Powershell_profile.ps1 cannot be loaded. The file is not digitally signed.

If you are seeing this, your PowerShell execution policy is either AllSigned or Restricted. You could be seeing this due to the addition of the Chocolatey profile (above question) for tab completion. You need to authenticode sign the PowerShell profile file, rename it, or remove it.

Reference: (you will need to join the group to see the message)

I'm getting a 403 unauthorized issue when attempting to use the community package repository.

It could be one of a few things:

You can use a tool like Fiddler to help determine what is going on.

Cloudflare uses Project Honeypot to determine if your IP address is flagged, such as if you have malware on your box that is sending spam emails. Go to Project Honeypot and put in your IP address - Check to see if your IP is flagged here.

If you determine it is CloudFlare blocking your IP (which is the issue 98% of the time), we may be able to get you whitelisted for Chocolatey:

Once this has been completed, you should have access to install Chocolatey and/or packages from the community repository.

I'm getting a 429 too many requests issue when attempting to use the community package repository.

This means your IP address has been flagged for too many requests. Please see Rate Limiting for details and actions.

Reference Errors:

I'm seeing Chocolatey / application / tool using 32 bit to run instead of x64. What is going on?

The shims are generated as "Any CPU" programs, which depend on the Enable64Bit registry value to be set to 1, which it is by default. A way to fix it is to issue the following command at the location where the prompt shows below:

  C:\Windows\Microsoft.NET\Framework64\v2.0.50727> Ldr64 set64

Any CPU 32-bit mode on 64 bit machine

A package is broken for me

Depening on where you are installing this package from, we suggest you first look at your log files for more detailed output on the logs (based on the failure instructions).

The package install failed with 1603

This is a generic MSI error code - you probably want to ensure you capture the log output from the MSI - if the package doesn't have it in the script, add it with --install-arguments '"/l*v c:\msi_install.log"' and then search the log file that is created for Return Value 3. This typically surrounds the actual error. Typically it can be anything from

Already referencing a newer version of 'packagename'

So you are attempting to install or upgrade and you get this strange message. But you know you have a more up to date package than Chocolatey thinks you do, at least in this instance.

This cryptic error typically means there is a stray nupkg somewhere in the structure. There is a tiny bug somewhere and rarely a nupkg will stick around when it should have been removed. Once we can determine where this happens we can fix it, until then we have a way to fix the issue manually.

This script may be even more helpful in helping you isolate those stray nupkg files (thank you ComFreek!):

# This script automatically filters the suspected candidates which are to be removed.

Get-ChildItem -Path "$env:ChocolateyInstall\lib" -Recurse -Filter "*.nupkg" | Where-Object {
  # Filter packages with version number
  $_.Name -match "^.*\.(\d+|\.){2,}\.nupkg"
} | Where-Object {
  # whose parent directory does not contain the same version number
  $_.Directory.BaseName -ne $_.BaseName
} | % {
  # Remove -WhatIf after having run this script and having double-checked (!) each file listed in the previous
  # run if it is really supposed to be removed (check the wiki link for information).
  Remove-Item $_.FullName -WhatIf

Not recognized as the name of a cmdlet, function, script file, or operable program

My PATH is not getting updated

First let's understand the scopes of the PATH environment variable. There is Machine, Current User (User), and Process environment variables. Process is a special scope that applies to the command shell (cmd.exe/powershell.exe). Process gathers Machine and User scopes when it first loads up AND ONLY when it first loads up. Yes, you read that right. This is a limitation of Windows, shells were never given the ability to see changes to environment variables and act accordingly. You traditionally need to install something, then close and reopen your shell to see it updated. That is a pretty clunky experience.

To understand this, open Powershell, then install something that updates the PATH, and run the following in that already open PowerShell command shell:

Contrast the two, notice there is a difference (there may be a lot of data to sift through).

When you update the Machine/User environment variables, you would also need to update the Process environment variables as it doesn't not see those changes. Fortunately, with Chocolatey, we have a tool called refreshenv that does this for you so you don't need to close and reopen the shell. If you run refreshenv and it doesn't have any effect, see RefreshEnv has no effect.

RefreshEnv has no effect

If you are in cmd.exe, it should just work. In PowerShell, you need to install the Chocolatey PowerShell profile first for the command to work.

Take note of whether it says "refreshing environment variables for cmd.exe" or "refreshing environment variables for powershell.exe". If you are in PowerShell and you see "cmd.exe" when you run refreshenv, then you need to do some additional work to get things set up. see Why does choco in{tab} not work for me?.

Options and/or parameters are not handled correctly

This problem is most likely to be seen if cutting and pasting Chocolatey commands from a document, instead of typing them in directly. Some documentation tools (notably Microsoft Word, but there are others) think they know best and automatically convert certain characters. The hyphen (-) character may become an en-dash (–) or em-dash (--). Similarly standard quotation marks (") may be converted into distinct open and close variants (""). Visually, the converted characters look very similar to the correct ones, but they are not functionally equivalent. Instead of cutting and pasting, try typing the command manually at the command prompt.

For example, if the hyphen for the -y (confirm all prompts) option had been converted into a visually similar character you would get the message "–y not installed. The package was not found with the source(s) listed.", and would also be prompted for confirmation before running scripts. Similarly, if you were using the --params option to pass parameters to the package, and suffered the same kind of cut and paste error, an attempt might be made to process the parameters string as if it were a package name, potentially resulting in an error like "The given path's format is not supported."

Chocolatey is selecting an older version of a dependency on upgrade

See next question

Chocolatey is attempting to downgrade a package that is a dependency of another package on upgrade

There are some possible reasons this happens, sometimes it is due to an existing package restricting the dependency version. Try running the following:

$nuspecs = gci $env:ChocolateyInstall\lib -recurse -filter *.nuspec

foreach ($nuspec in $nuspecs) {
  [xml]$nuspecContent = Get-Content $nuspec.FullName

  $dependencies = $nuspecContent.package.metadata.dependencies.dependency
  if ($dependencies -ne $null) {
    Write-Host "$($ v$($nuspecContent.package.metadata.version) dependencies:"
    foreach ($dependency in $dependencies) {
      $dependencyOperator = ">="
      if (!$dependency.version) { $dependencyOperator = "" }
      elseif ($dependency.version.Contains('[')) { $dependencyOperator = "=" }
      $dependencyVersion = $dependency.version
      if (!$dependencyVersion) { $dependencyVersion = "{Any Version}"}
      Write-Host " - $($ $dependencyOperator $($dependencyVersion)"

Inspect the results to see if you have anything restricting the version of your package to an older version.

You may also wish to clean the cache to verify that things are good to go. The cache should get cleaned automatically, but take a look at %LocalAppData%\NuGet\Cache and clean out any nupkgs in there. Head to %TEMP% and look for "NuGetScratch" and "x\NuGet", clean those up as well.

If you have done this and are still seeing issues, it is time to capture a trace log and Fiddler or Wireshark output. Fiddler is a good place ot start. Start up one of those tools and make sure it is configured correctly to capture output (we won't go into that here). Now try your command again with --trace and pipe the output to a file. In cmd.exe, you simply add this to the end > installation.log, with PowerShell, you pipe it like this: | Out-File ".\installation.log". Save the output of Fiddler/Wireshark and provide those files back to the issues log or your support team.

Also take a look at Already referencing a newer version of 'packagename'.

Package not installed. An error occurred during installation: Unable to resolve dependency

If you have determined all of this is good to go, take a look at what Chocolatey tells you when you run with -dv --noop and see how it is setting sources, etc.

Package not installed. The package was not found with the source(s) listed.

If you have determined all of this is good to go, take a look at what Chocolatey tells you when you run with -dv --noop and see how it is setting sources, etc.

Access to the path is denied.

You may be attempting to use Chocolatey or upgrade a package and suddenly you are getting access denied errors starting mid-install/upgrade.

Unfortunately, this is likely to cause your install to be unusable until you fix the issue.

A corrupt registry file exists

You are receiving the following error when running Chocolatey commands:

powershell A corrupt .registry file exists at C:\ProgramData\chocolatey\.chocolatey\$application\.registry.bad. Open this file in a text editor, and remove/escape any characters that are regarded as illegal within XML strings not surrounded by CData. These are typically the characters &, `<`, and `>`. Again, this is an XML document, so you will see many < and > characters, so just focus exclusively in the string values not surrounded by CData. Once these have been corrected, rename the .registry.bad file to .registry. Once saved, try running the same Chocolatey command that was just executed, to verify problem is fixed. NOTE: It will not be possible to rename the file in Windows Explorer. Instead, you can use the following PowerShell command: Move-Item .\.registry.bad .\.registry

    $folders = Get-ChildItem "$env:ChocolateyInstall\.chocolatey" -Recurse |
               Where-Object {$_.Name -match "reg" } |
               Select-Object DirectoryName -Unique

    foreach ($Folder in $Folders) {
        Write-Warning -Message "Enumerating $($Folder.DirectoryName)"

        if (Test-Path "$($Folder.DirectoryName)\.registry.bad") {

            Write-Warning -Message "Found a .registry.bad file in $($folder.DirectoryName), checking for .registry"

            if (Test-Path "$($Folder.DirectoryName)\.registry") {

                Write-Warning -Message "Found a .registry file, can safely delete .bad file"

                Remove-Item "$($folder.DirectoryName)\.registry.bad" -Force -Confirm:$false

                Write-Warning -Message "Successfully removed $($folder.DirectoryName)\.registry.bad"


            else {

                Write-Warning -Message "No .bad file exists in $($folder.DirectoryName), renaming file"

                Move-Item "$($Folder.DirectoryName)\.registry.bad" "$($Folder.DirectoryName)\.registry"