Skip to end of metadata
Go to start of metadata


This is a general troubleshooting and technical FAQ document.

Common Errors has common error messages for Chef-Client, Knife and Chef-Server - and their solutions. For an "About Chef" FAQ, see Chef-FAQ



What is the current version of Chef? Do I need to upgrade?

  • The current version of Chef is 11.6.0 Release Notes <-- This is not working as of 2013-05-21, when current version is 11.x but page still shows a 10.x version
  • The current version of Ohai is 6.14.0

Private Chef users will have migrations to new versions addressed through a jointly developed migration plan and upgrade implementation. Please follow up with your Private Chef administrator for additional information.

Hosted Chef will always be enabled with the current version, and with functionality sufficient to support use of pre-release versions. When new versions of Chef and the Opscode API are released, they will be immediately available to you on Hosted Chef – data migrations and backwards compatibility taken care of by Opscode. You can upgrade to new release chef-client versions and ohai clients as convenient for you, in order to gain the advantage of new releases functionality.

Open Source Chef users should upgrade their chef-server(s) and chef-clients to the newest version that provides the functionality and bug fixes they require. Another driver for upgrades would be availability of support resources from Opscode and the community. Release Notes has a listing of all of the current supportable versions of Chef. Versions older than 0.9.0 should be considered obsolete at this point.

What is an FQDN and why do I need one?

An FQDN is a "Fully Qualified Domain Name." By default, Chef Client uses the node's FQDN to uniquely identify node names to the server if the node name was not explicitly set.

When using Passenger or Apache Proxy configurations for the Chef Server, the FQDN is used for the SSL certificate CN - canonical name.

Do you have a video, or offer training on Chef?

We have both! At Guides you’ll find a number of “Walkthrough Guides” that take you step by step through the installation of 6 different common server stacks including:

With detailed documentation and an accompanying screencast, you can go at your own pace and learn how to use Chef for your environment – all while setting up multiple server stacks you can put to use.

There are also “How To Guides” available on:

For a broader review of Chef, there’s a Webcast of "Why Chef" which is aimed at users new to Chef. And, if you’d like, following registration, we’ll be happy to send you the Open Training Materials for free.

Opscode Community Summit

Registration is open for the third annual Opscode Community Summit - November 12 & 13 in Seattle, WA, USA!

Space is limited so register today!


Why do I need RubyGems installed from source?

You don't have to install RubyGems from source. However, Opscode recommends it when installing Chef from RubyGems. Installing from source ensures consistency across platforms, as we can reasonably expect it to install in the same locations. RubyGems doesn't follow Filesystem Hierarchy Standard on Linux, to which Debian and Ubuntu adhere, which may cause pathing problems that are sometimes difficult to track down.

For example on Debian and Ubuntu, using the RubyGems distro package doesn't install binary programs to /usr/bin, instead they live in /var/lib/gems/1.8/bin, which isn't in the default user $PATH. This causes confusion for some users, as when they install Chef they can't run chef-client, chef-solo or even chef-server. Thus we recommend installing RubyGems from source when installing Chef from RubyGems on these distributions.

What if I have multiple versions of the same Gem?

Having multiple versions of the same gem can prove problematic. Ruby can have unpredictable issues and responses in that scenario, which can affect your environment and the success of Chef runs.

There are some knife-plugins that require a specific gem version, if that is the case, it will be specified in the plugins gemspec. To remove a specific gem sudo gem uninstall GEMNAME -v VERSION#. To remove all older versions of any gems, run sudo gem cleanup. It will leave only the newest versions of installed gems.

Where can I find Chef's logs?

Chef logs to standard out (STDOUT) for all its programs chef-client/chef-solo, chef-indexer, chef-server. This can be changed by adjusting the configuration value of "log_location" in the appropriate configuration file. For example,


runit logs

When installing Chef via the bootstrap recipe, Chef is configured to use the runit init system. In this case your logs are located in /etc/sv/PROGRAM/log/main/current

How can I get more log information?

By default, Chef's programs have error level logging. To get more information, turn on info level. This can be done for a single execution of the program with -l or by changing the verbose value to :info (the colon is significant). For example,


You can also setup Chef to have debug level logging. This can be done with two executions of the program with -V or by changing the verbose value to :debug (The colon is significant). For example,


If you are requesting help on IRC or the Mailing List, you may be asked to provide debug log output.

Connection refused for localhost:5984, what is listening on 5984?

By default, CouchDB listens on port 5984. You need to make sure it is installed and running for your Chef Server. The best way to make sure it is running is to make an http request:

Why doesn't Chef work on XYZ platform?

Chef detects the platform with Ohai, and looks up providers to use for various resources in the platform.rb file. If a platform is not defined in this file with specific providers, the :default values are used for each resource. Not all resources need a platform-specific provider. Chef allows you to easily create new providers within your cookbooks, but we also appreciate new contributions to Chef.

How do I delete a node with an empty name?

In some situations a node might get saved to the Chef Server with an empty name. When viewed in the Node List in the WebUI, the name is completely blank. This can be fixed by removing the node_ document from the CouchDB. You can do this in Futon, the CouchDB webui, or by interacting with the CouchDB API with a tool such as curl.

Futon - CouchDB WebUI

  • Navigate to http://localhost:5984/_utilson the chef server with your web browser. Set up an SSH tunnel if necessary.

  • Click on 'chef' in the database list.
  • Click on the document 'node_' with ID: node_.
  • Click 'Delete Document'.

Refresh the Chef Server nodes list and the node will be gone.

CouchDB API via Curl

Removing the node via the CouchDB API with a tool like curl is very straightforward.

  • Find the revision of the blank node_ document, otherwise CouchDB will display a conflict error.

  • Delete the node.

  • The node will now show as deleted.

Also, if you refresh the Chef Server WebUI nodes list the node will be gone.

How do I delete a malformed Chef Server client (Say, one with spaces in the name)

Follow the same procedure as for nodes above to discover the id of the document

Futon - CouchDB WebUI

  • Navigate to http://localhost:5984/_utilson the chef server with your web browser. Set up an SSH tunnel if necessary.

  • Click on 'chef' in the database list.
  • Click on the document 'client_XXXX' with ID: client_XXXX
  • Click 'Delete Document'.

Why is my Chef run crashing on a require statement for a gem that should have been installed via Chef?

Recipes are evaluated during the node Convergence phase of the Chef run, which happens in two phases. The first phase is 'compile' phase where ruby code (like require 'sys-filesystem') is evaluated, and the resources are added to the resource collection. The second is the 'execute' phase where the actions are taken on the resources in the collection. (See Anatomy of a Chef Run for more information).

In order to use a gem in the same run that the gem is installed, you have to create that resource in the compile phase. To install the gem in the compile phase, use this:

See our Opscode blog post for additional information.

Is there a recommended approach for managing individual credentials and knife.rb when multiple developers will be using the same chef-repo?

We recommend checking the knife.rb into your chef-repo (CHEF_REPO/.chef/knife.rb) and then having user specific (or sensitive) values dynamically filled using a series of environment variables. Since the knife.rb file is just Ruby this is pretty easy to do. For example:

This approach allows you to control who has a copy of the org validation.pem but allows you to share your chef code with the company as a whole (yeah devops!). Some companies even have multiple organizations and switching between them is as easy as cd-ing into a different chef repository!

May I use RVM to install Ruby and/or RubyGems that the chef-client runs under?

The recommended method to install chef as a client is as a RubyGem with RubyGems installed from source, or from our APT repository on Ubuntu and Debian.

We don't recommend using RVM to install Ruby/RubyGems that the chef-client runs under, because that can cause system PATH and Ruby loadpath errors. The knife bootstrap subcommand makes installing Chef much easier with the templates that it ships with.

Many however do use RVM to install Ruby on the workstations where they use knife, but that is a separate matter than running Chef on client nodes. Note: If you're installing Chef under RVM on your workstation for using knife and managing the chef repository (chef-repo), you don't need to use sudo, and probably shouldn't as it may result in pathing differences to install the gems. The problem will be sudo scrubbing the environment variables rvm uses to keep track of which ruby and rubygems installation you're using. For example, Opscode star Dan Deleo's rvm installation is using the following:

If you run sudo env you can see that these variables were "scrubbed" by sudo. In order to work around the problem, try running the command as sudo -E chef-client. If that doesn't work, you might need to run a shell as root with the rvm environment, by running sudo -E bash and then just chef-client. Or, you should be able to simply do gem install chef as your normal user without sudo and it will install the gems under your default ruby in rvm.

Alternatively, if you'd like to run chef client on a machine who's Rubies are under the control of RVM, you'll need to accept installing the chef gem in the global gemset. It'll be available in all your gemsets. The caveat here is you might find your self with gem version conflicts.

That should work in place of the two step sudo -E bash then chef-client method put forth above, but again, you may find that you are dealing with gem version conflicts.

What if an Opscode service appears to be unavailable? For instance, what if I'm using Hosted Chef and I am unable to access it?

Hosted Chef is built from the ground up by Opscode to be fully multi-tenant, horizontally scalable, and highly available. Opscode has several external monitors of it, and all Opscode web service functions and services, enabling rapid response to any emergent availability issues.

Occasionally, periodic maintenance is necessary to maintain efficient functionality and performance for all services. Any planned maintenance is announced in advance via the Opscode Status site. Emergent issues in Hosted Chef availability, or that of other Opscode services such as Cookbooks, Open Source Tickets or this Chef Wiki will also be posted at Opscode Status.

Opscode customers who use Twitter can also receive availability status announcements by following Opscode Status on Twitter. Please also follow Opscode on Twitter for company and product news and information. If you are having issues in accessing any shared Opscode services, and find no announcement at Opscode Status or through following Opscode Status on Twitter, please send an email to describing the issue you are experiencing.

Note: Help on issues specific to running your own Chef Server environment and use of Chef should be addressed through Support Resources.

How can I ensure a notified action is processed, regardless of the full chef-client run completing?

Delayed notifications do not run after an error by design. An example supporting this behavior is the case where you are making changes to the web server config but something fails. A restart would bring the service down whereas fixing the problem and re-running chef-client successfully will not.

The general recommendation to alleviate this problem during development is to develop in an environment where you can occasionally as a matter of practice "start from scratch". Much more difficult to detect errors can happen with this same "broken first run" problem.

In particular cases, you may want to ensure the action gets taken immediately, which will ensure the rebuild happens regardless of what happens later in the run.

The Resources Notification Option page has more detail and additional examples.

How do I create a recipe that will only execute an action on the first run of chef-client?

Creating a "First Run Only" Resource provides information on how to accomplish this - however it is an approach that should be used sparingly. Most resources are idempotent by construction and do not require the methods discussed. Whenever possible, it is best to use an idempotent resource.

How do I extend a base cookbook to account for the use of the IUS RPMs?

We would suggest just modifying the package names in your copy of the COOKBOOK::package recipe. Our cookbooks are meant to be a starting point, and we expect community members to modify then and personalize for their infrastructure. That's why we have build in tools like knife cookbook site install which allow easy upstream tracking.

That said, there are approaches to add logic to change the package names based on the YUM sources. The following examples use the PHP Cookbook.

The main thing to take note of in the above example is the new line in the pkgs.each block. This basically searches for the existence of the ius yum source and then appends the u to the package name.


How can I run the chef-client periodically?

If you want, you can run the Chef Client as a persistent daemon. To do this, make your startup script for the chef client execute something like:

The -i option provides an Interval - it's how often the Chef client will attempt to wake up and Converge this node. The -s option is the Splay - a random piece of time added to the interval, which helps avoid the thundering herd problem.

The chef-client cookbook available on the community site provides an easy way to manage the chef-client configuration with chef itself! See Chef Client for additional information.

What is the best way to manage software that needs regular updates or patches?

First, you will want to determine the type of change that needs to be made regularly.

  • If the change is to a behavior, such as a patch, you will want to control this with a recipe or role.
  • If the change is to data, such as with DNS or the current software version, you will want to control this with a data bag or attribute.

The best way to apply regular patches is to specify the actual version in the package that is run over time, and change that version to a new one after testing it. If you do this frequently you can data-drive this change by dropping an attribute into the role that includes this cookbook. When a new version comes out:

  1. drop the version string into that role's development environment list and test it, then
  2. update the version on the role's production environment run_list.

This way you are only changing a role. It is possible to apply patches with 'action :upgrade' but this will control when it is updated and not necessarily what version it is updated to.

The best way to apply data updates like DNS is to separate that data into a data bag and then render from the data bag into a zone file via the recipe and chef template.

After applying the update you could run something like this:

To select the nameservers in your fleet, with appropriate additional command line args for authentication, parallelism, etc. More information on the knife ssh command can be found in the Knife Wiki Article.

Any tuning recommendations for those with a large LDAP user base?

As Ohai gathers information about your operating system while it is running, you can make some modifications to the chef client configuration to increase performance when dealing with large installations or large user bases.

1. Modify nodes.rb to reduce automatic_attrs size

2> Modify Ohai to read passwords directly

3> Update standard bootstrap template

4> Disable undesirable Ohai plugins

If you do not want some Ohai plugins to run, you can disable them by doing something like the following within /etc/chef/client.rb:

(You may desire to choose other plugins that the ones in the above example.) See Disabling Ohai Plugins for additional information.

I have one-off nodes in my environment and need to manage them uniquely. How do I do this with Chef?

This is a common question from people that follow a pattern of naming schemes for hostnames and/or fully-qualified domain names. Because the Chef Server API provides a search interface to rich metadata about Chef nodes, we do not recommend treating anything as a "Unique and Beautiful Snowflake." Instead, we recommend that nodes be treated as ephemeral, and that the discovered attributes (by Ohai) and roles (assigned in the run-list) describe the node.

If a node is truly unique, give it a role that describes its functionality, and use node attributes set in the role as required to be used in its recipes that affect the required "one-off" configuration. That way if the node goes away for some reason (deleted by accident, hardware fails, etc), its functionality can be replaced easily by applying the role to another node.

How do I recreate my validator client when using Hosted Chef?

If you accidentally delete your validator client, you will get a 403 error when trying to create new clients.

You will need to create the validator key again and fix it's permissions by using the following directions. In these directions, ORGANIZATION should be replaced by your organizations short name.

1. Click on the 'clients' tab at
2. Click on the 'create' sub-tab
3. Enter "ORGANIZATION-validator" as the name, substituting your organization's name, and click on the 'create' button
4. Click on the 'Download API Key' link to get a copy of the new ORGANIZATION-validator.pem. Save a copy of this private key in a save place, this will be your organization's new validator key.
5. Now we will need to fix the permissions on the validator client. Click on the 'list' sub-tab.
6. Click on the 'edit permissions' sub-tab
7. Check the 'create' and 'list' checkboxes for the ORGANIZATION-validator client and click on the 'update permissions' button

NOTE: 6. Should produce a link in the location bar of your browser that looks like ""

Are there common errors and error messages that I should be aware of?

Common Errors contains errors that arise with Chef Client and Knife and their suggested fixes. If your issue is neither on this page, nor on Common Errors, please return to Support to seek assistance.

  • None
  1. Nov 29, 2012


    Anyone please help me out on how to work with chef. In what basis I have to relate Chef, Vagrant, Cent OS, Chef git, SSH. Please share your ideas.