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?
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.
Do you have a video, or offer training on Chef?
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.
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
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
Where can I find Chef's logs?
Chef logs to standard out (STDOUT) for all its programs
When installing Chef via the bootstrap recipe, Chef is configured to use the runit init system. In this case your logs are located in
How can I get more log information?
By default, Chef's programs have
You can also setup Chef to have
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
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
Futon - CouchDB WebUI
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.
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
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
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
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
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 firstname.lastname@example.org 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
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
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:
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.
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:
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 http://manage.opscode.com
NOTE: 6. Should produce a link in the location bar of your browser that looks like "https://manage.opscode.com/clients/_acl"
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.