:title: Troubleshooting Deis :description: Resolutions for common issues encountered when running Deis. .. _troubleshooting_deis: Troubleshooting Deis ==================== :Release: |version| :Date: |today| .. toctree:: troubleshooting-store Common issues that users have run into when provisioning Deis are detailed below. Logging in to the cluster ------------------------- Deis runs on CoreOS, so connecting is as simple as using ``ssh``. CoreOS's default username is ``core``. Use the SSH key you provisioned the cluster with. Connect to the public IP address of one of your nodes (or use "convenience" DNS records if you've set them up). .. code-block:: console $ ssh core@deis-1.example.com -i ~/.ssh/deis Troubleshooting etcd -------------------- Sometimes issues with Deis are caused by latency between CoreOS hosts. A telltale sign of this is if all of the Deis components on a single machine crash. To aid in debugging etcd, we've created a system service that is installed but not started when you deploy CoreOS using our provision scripts. To start this service, run ``sudo systemctl start debug-etcd`` on a CoreOS machine in your cluster. This starts a service which queries etcd's state once per second. Watching this output with ``journalctl -fu debug-etcd`` makes it easy to spot heartbeat timeouts or other abnormalities which will lead to issues running Deis successfully. A deis-store component fails to start ------------------------------------- For information on troubleshooting a ``deis-store`` component, see :ref:`troubleshooting-store`. Any component fails to start ---------------------------- Use ``deisctl status `` to view the status of the component. You can also use ``deisctl journal `` to tail logs for a component, or ``deisctl list`` to list all components. Failed initializing SSH client ------------------------------ A ``deisctl`` command fails with: 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'. Did you remember to add your SSH key to the ssh-agent? ``ssh-add -L`` should list the key you used to provision the servers. If it's not there, ``ssh-add -K /path/to/your/key``. All the given peers are not reachable ------------------------------------- A ``deisctl`` command fails with: 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'. The most common cause of this issue is that a new discovery URL wasn't generated and updated in ``contrib/coreos/user-data`` before the cluster was launched. Each Deis cluster must have a unique discovery URL, or else ``etcd`` will try and fail to connect to old hosts. Try destroying the cluster and relaunching the cluster with a fresh discovery URL. You can use ``make discovery-url`` to automatically fetch a new discovery URL. Could not find unit template... ------------------------------- If you built ``deisctl`` locally or didn't use its installer, you may see an error like this: .. code-block:: console $ deisctl install platform Storage subsystem... Could not find unit template for store-daemon This is because ``deisctl`` could not find unit files for Deis locally. Run ``deisctl help refresh-units`` to see where ``deisctl`` searches, and then run a command such as ``deisctl refresh-units --tag=v1.6.1``, or set the ``$DEISCTL_UNITS`` environment variable to a directory containing the unit files. Other issues ------------ Running into something not detailed here? Please `open an issue`_ or hop into #deis on Freenode IRC and we'll help! .. _`open an issue`: https://github.com/deis/deis/issues/new