doc/develop/west/troubleshooting.rst

.. _west-troubleshooting:

Troubleshooting West
####################

This page covers common issues with west and how to solve them.

``west update`` fetching failures
*********************************

One good way to troubleshoot fetching issues is to run ``west update`` in
verbose mode, like this:

.. code-block:: shell

   west -v update

The output includes Git commands run by west and their outputs. Look for
something like this:

.. code-block:: none

   === updating your_project (path/to/your/project):
   west.manifest: your_project: checking if cloned
   [...other west.manifest logs...]
   --- your_project: fetching, need revision SOME_SHA
   west.manifest: running 'git fetch ... https://github.com/your-username/your_project ...' in /some/directory

The ``git fetch`` command example in the last line above is what needs to
succeed.

One strategy is to go to ``/path/to/your/project``, copy/paste and run the entire
``git fetch`` command, then debug from there using the documentation for your
credential storage helper.

If you're behind a corporate firewall and may have proxy or other issues,
``curl -v FETCH_URL`` (for HTTPS URLs) or ``ssh -v FETCH_URL`` (for SSH URLs)
may be helpful.

If you can get the ``git fetch`` command to run successfully without prompting
for a password when you run it directly, you will be able to run ``west
update`` without entering your password in that same shell.

"'west' is not recognized as an internal or external command, operable program or batch file.'
**********************************************************************************************

On Windows, this means that either west is not installed, or your :envvar:`PATH`
environment variable does not contain the directory where pip installed
:file:`west.exe`.

First, make sure you've installed west; see :ref:`west-install`. Then try
running ``west`` from a new ``cmd.exe`` window. If that still doesn't work,
keep reading.

You need to find the directory containing :file:`west.exe`, then add it to your
:envvar:`PATH`. (This :envvar:`PATH` change should have been done for you when
you installed Python and pip, so ordinarily you should not need to follow these
steps.)

Run this command in ``cmd.exe``::

  pip3 show west

Then:

#. Look for a line in the output that looks like ``Location:
   C:\foo\python\python38\lib\site-packages``. The exact location
   will be different on your computer.
#. Look for a file named ``west.exe`` in the ``scripts`` directory
   ``C:\foo\python\python38\scripts``.

   .. important::

      Notice how ``lib\site-packages`` in the ``pip3 show`` output was changed
      to ``scripts``!
#. If you see ``west.exe`` in the ``scripts`` directory, add the full path to
   ``scripts`` to your :envvar:`PATH` using a command like this::

     setx PATH "%PATH%;C:\foo\python\python38\scripts"

   **Do not just copy/paste this command**. The ``scripts`` directory location
   will be different on your system.
#. Close your ``cmd.exe`` window and open a new one. You should be able to run
   ``west``.

"invalid choice: 'build'" (or 'flash', etc.)
********************************************

If you see an unexpected error like this when trying to run a Zephyr extension
command (like :ref:`west flash <west-flashing>`, :ref:`west build
<west-building>`, etc.):

.. code-block:: none

   $ west build [...]
   west: error: argument <command>: invalid choice: 'build' (choose from 'init', [...])

   $ west flash [...]
   west: error: argument <command>: invalid choice: 'flash' (choose from 'init', [...])

The most likely cause is that you're running the command outside of a
:ref:`west workspace <west-workspace>`. West needs to know where your workspace
is to find :ref:`west-extensions`.

To fix this, you have two choices:

#. Run the command from inside a workspace (e.g. the :file:`zephyrproject`
   directory you created when you :ref:`got started <getting_started>`).

   For example, create your build directory inside the workspace, or run ``west
   flash --build-dir YOUR_BUILD_DIR`` from inside the workspace.

#. Set the :envvar:`ZEPHYR_BASE` :ref:`environment variable <env_vars>` and re-run
   the west extension command. If set, west will use :envvar:`ZEPHYR_BASE` to
   find your workspace.

If you're unsure whether a command is built-in or an extension, run ``west
help`` from inside your workspace. The output prints extension commands
separately, and looks like this for mainline Zephyr:

.. code-block:: none

   $ west help

   built-in commands for managing git repositories:
     init:                 create a west workspace
     [...]

   other built-in commands:
     help:                 get help for west or a command
     [...]

   extension commands from project manifest (path: zephyr):
     build:                compile a Zephyr application
     flash:                flash and run a binary on a board
     [...]

"invalid choice: 'post-init'"
*****************************

If you see this error when running ``west init``:

.. code-block:: none

   west: error: argument <command>: invalid choice: 'post-init'
   (choose from 'init', 'update', 'list', 'manifest', 'diff',
   'status', 'forall', 'config', 'selfupdate', 'help')

Then you have an old version of west installed, and are trying to use it in a
workspace that requires a more recent version.

The easiest way to resolve this issue is to upgrade west and retry as follows:

#. Install the latest west with the ``-U`` option for ``pip3 install`` as shown
   in :ref:`west-install`.

#. Back up any contents of :file:`zephyrproject/.west/config` that you want to
   save. (If you don't have any configuration options set, it's safe to skip
   this step.)

#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,
   you will get the "already in a workspace" error message discussed next).

#. Run ``west init`` again.