Troubleshooting

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.

General

If you are unable to find answers to your questions here, please see https://chocolatey.org/support (FOSS and Licensed) and https://chocolatey.org/bugs 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('https://chocolatey.org/in ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + 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 https://chocolatey.org/support 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: https://groups.google.com/d/msgid/chocolatey/40736df7-7f3f-4be7-929d-1606be0e3a62%40googlegroups.com (you will need to join the group to see the message)

ERROR: This package does not support 64 bit architecture.

This message is from https://github.com/chocolatey/choco/issues/527 - 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.

References:

"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: https://groups.google.com/d/msgid/chocolatey/d11d8eb2-74b3-4c2c-b0bb-d1a1ed3df389%40googlegroups.com (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.

Runtime

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:

  • If this is the same shell that the upgrade occurred in, the message states you need to update your profile - run . $profile. Try that first, then try restarting your shell and see if it takes hold.
  • If it still doesn't work, it means there was a failure setting the profile with the module.
  • This could be due to PowerShell Execution Policy settings. Run Get-ExecutionPolicy - if it is set to Restricted you need to adjust that to something like RemoteSigned. See about execution policies (link)
  • If that is fine, then we need to look at your "$profile". Run type $profile. Examine the output. You should have something like this in the file:
# Chocolatey profile
$ChocolateyProfile = "$env:ChocolateyInstall\helpers\chocolateyProfile.psm1"
if (Test-Path($ChocolateyProfile)) {
  Import-Module "$ChocolateyProfile"
}
  • If you don't see that, let's add it. Run Write-Host $profile - note the location and open it up in an editor (anything but plain old notepad.exe for the love of..., well your favorite editor).
    • Now let's add that text above to the profile. Save and close the file. Now type . $profile to update your current Shell. Give choco in<tab> a shot again. If it still doesn't work we'll need to examine something a bit more deeply about your environment. Please submit an issue so we can investigate.

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: https://groups.google.com/d/msgid/chocolatey/58ef0ece-5e2a-4c2c-82a8-10e1711bdd3f%40googlegroups.com (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 have a proxy that you need to configure
  • It is being blocked in your organization
  • We broke something (this is the least likely reason)
  • CloudFlare has blocked your IP due to reasons (99% of the time, this is the issue)
  • The Chocolatey Community Team may have blocked access due to excessive use - see excessive use for details

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 - http://www.projecthoneypot.org/search_ip.php. 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:

  • Go to https://chocolatey.org/contact (NOTE: If you are completely blocked from accessing the site, contact us through Gitter instead)
  • Select Blocked IP Address in "Send message to" drop down (this is important to get it routed to the right folks)
  • IMPORTANT: Let us know what's going on along with your IP address so we can talk about whitelisting options and get you moving forward.
  • Oh, and be sure to run some antivirus scans and remove any found malware (and maybe find a better antivirus scanner).

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:

  • Exception calling "DownloadFile" with "2" argument(s): The remote server returned an error: (429) Too Many Requests
  • The remote server returned an error: (429) Too Many Requests. Too Many Requests

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

  • The installer doesn't allow reinstalling the same version
  • There is a pending reboot
  • Some prerequisite has not been met
  • The installer doesn't allow installing an older version
  • etc - it's a generic error like we said

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.

  • Open PowerShell and run the following script:
  • gci -Path "$env:ChocolateyInstall\lib" -Recurse -Filter "*.nupkg" | %{ $_.FullName }
  • Look for any nupkg files that should not be there. Typically this is probably going to be a nupkg with a version number in the name in a folder that doesn't have a version number in the name of the folder.
  • Delete the offending nupkg from the folder.
  • Then everything should be back to normal again.

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

  • With Chocolatey (choco) itself? Close and reopen the shell as the install didn't ensure the PATH was updated in the current shell.
  • With something you installed? See My PATH is not getting updated.

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:

  • Write-Host "$((Get-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment\' -Name 'PATH').Path); $((Get-ItemProperty -Path 'HKCU:\Environment' -Name 'PATH').Path)" - This is Machine/User PATH pulled directly from the registry.
  • $env:PATH - This is Process PATH

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 "$($nuspecContent.package.metadata.id) 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 " - $($dependency.id) $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

  • Most Likely: This occurs when you have overridden default sources and/or have not specified enough sources explicitly.

    If you are installing from a local folder, you have likely passed in an explicit source (-s|--source), which overrides all default sources. So that dependency needs to be either already installed or sitting in one of the sources you explicitly specified.

    Fix: If you are testing a package you may push to the community repository later, you may want to ensure you specify the source like this: --source="'.;https://chocolatey.org/api/v2'".

  • Sometimes this occurs when the version or version range being specified for the dependency not being available. Fix: fix the packaging to use the right version range or ensure that their is a package available that meets the version constraints.

  • Also check the package id of the dependency for typos. Fix: Make sure that package id does exist on the source repositories you are using.

  • The dependency is a prerelease. Fix: Make sure you are using --pre so that it is discoverable.

  • You are specifying sources but attempting to install from a path to a nupkg/nuspec.

    If you are calling choco install .\path\to\pkg\name.version.nupkg, this means the same as explicitly calling chocho install <name> --version --source="'c:\full\path\to\pkg\'" (if it is on the 'c:' drive) as the source. So it doesn't matter if you also explicitly pass source locations, it will not work.

    By the way, calling install directly from a nupkg/nuspec can be an anti-pattern. Use it VERY rarely, like not at all if you can help it.

    Fix: Stop pointing directly to the nupkg/nuspec. Call choco install name -s . instead.

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.

  • Look at the sources that were used.

    • If you are using the default sources, ensure the package exists.
    • If you are passing an explicit source, that is all that will be used. Make sure you
  • Ensure you are not attempting to install a prerelease (identified by a - in the version, e.g. 1.2.3-a).

  • Make sure you have a compiled package. That ends in the extension ".nupkg"

    A ".nuspec" is part of an uncompiled package. For installation you need to ensure that is compiled. See choco pack -?.

  • For your next step in troubleshooting, please see 403 unauthorized issues.

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.

  • Run cmd.exe /c cacls.exe "%ChocolateyInstall%" and verify you are in one of the accounts that has permission.

    Chocolatey doesn't add any additional locking on files/folders under that (aside from the additional setting in the logs folder for file appending).

  • Check to see if the folder has been locked by another process.

    If you've verified you are an administrator and can not get into that folder, it's likely the folder was attempted to be deleted, but another process was accessing that folder and is holding a lock on it. You can use Handles (SysInternals) or something like LockHunter to attempt to find out if there is a lock on the folder. If there is, you normally would just need to close the process in question so the folder can be deleted.

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:

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
  • The following script can be used to remediate this error
    $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"

            }#inner_if

            else {

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

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

            }#else

        }#outer_if

    }#foreach