.. _troubleshooting:

Troubleshooting
#########################

Links to common errors when running |popy| models are shown in :numref:`table_troubleshoot`:-

.. _table_troubleshoot:

.. list-table:: Solutions to common |popy| issues
    :header-rows: 1
    
    * - Problem
      - Solution
      
    * - :ref:`popy_run_not_recognized`
      - run :ref:`popy_env` before :ref:`popy_run`

    * - :ref:`popy_run_not_recognized_as_cmdlet`
      - run :ref:`popy_env` before :ref:`popy_run`

    * - :ref:`popy_env_not_recognized`
      - put 'popy_env.bat' on system path 
      
    * - :ref:`popy_env_not_recognized_as_cmdlet`
      - put 'popy_env.bat' on system path 
      
    * - :ref:`popy_env_permission_error`
      - use :term:`dos prompt` to call :ref:`popy_env`
      
      

.. _popy_run_not_recognized:
      
'popy_run' is not recognized
===============================

Scenario
~~~~~~~~~

You get this error if you open a |dosp| and attempt to run the :ref:`popy_run` program as follows:-

.. code-block:: doscon

    $ popy_run
    
Then get the response:-
    
.. code-block:: doscon
    
    'popy_run' is not recognized as an internal or external command,
    operable program or batch file.
   
Cause
~~~~~~

The problem is that the |popy| environment has not been enabled, so |windoze| does |not| know where to look for the command 'popy_run'.

Solution
~~~~~~~~~
   
The solution is to run :ref:`popy_env` before you do :ref:`popy_run`, as follows:-

.. code-block:: doscon

    $ popy_env
    $ popy_run 
    
:ref:`popy_run` should now work as expected.

.. _popy_run_not_recognized_as_cmdlet:

The term 'popy_run' is not recognized as the name of a cmdlet
===============================================================

Scenario
~~~~~~~~~

You get this error if you open a |psp| and attempt to run the :ref:`popy_run` program as follows:-

.. code-block:: ps1con

    $ popy_run
    
Then get the response:-
    
.. code-block:: ps1con
    
    popy_run : The term 'popy_run' is not recognized as the name of a cmdlet, function, script file, or operable program.
    Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
    At line:1 char:1
    + popy_run
    + ~~~~~~~~
        + CategoryInfo          : ObjectNotFound: (popy_run:String) [], CommandNotFoundException
        + FullyQualifiedErrorId : CommandNotFoundException
   
Usually in difficult to read red on blue writing.
   
Cause
~~~~~~

The problem is that the |popy| environment has not been enabled, so |windoze| does |not| know where to look for the command 'popy_run'.

Solution
~~~~~~~~~
   
The solution is to run :ref:`popy_env` before you do :ref:`popy_run`, as follows:-

.. code-block:: ps1con

    $ popy_env
    $ popy_run 
    
:ref:`popy_run` should now work as expected.


.. _popy_env_not_recognized:

'popy_env' is not recognized
==============================

Scenario
~~~~~~~~~

You start a |dosp| and type the following command:-

.. code-block:: doscon

    $ popy_env

Then you see the message:-

.. code-block:: doscon

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

Cause
~~~~~~~

|popy| is either not installed or your system path is not configured correctly.


Solution
~~~~~~~~~
    
In a |dosp| type:-

.. code-block:: doscon

    $ echo %PATH%
 
In order for |popy| to work the directory containing 'popy_env.bat' on your machine, needs to be listed in the |windoze| system path. If the 'popy_env.bat' directory is |not| present, then you need to manually add it. In a dos prompt you can do this:-

.. code-block:: doscon

    $ set PATH=%PATH%;c:\PoPy
    
Where 'c:\\PoPy' is the recommended install directory for |popy|.
 
To save the path permanently do:-

.. code-block:: doscon

    $ setx PATH %PATH%
 
Note you probably need **admin rights** to use the 'setx' command. Once your |windoze| path is sorted out you should be able to run and test the |popy| environment as follows:-
 
.. code-block:: doscon
    
    $ popy_env
    $ popy_info
   
.. _popy_env_not_recognized_as_cmdlet:
   
The term 'popy_env' is not recognized as the name of a cmdlet
===============================================================

Scenario
~~~~~~~~~

You start a |psp| and type the following command:-

.. code-block:: ps1con

    $ popy_env

Then you see the message:-

.. code-block:: ps1con

    popy_env : The term 'popy_env' is not recognized as the name of a cmdlet, function, script file, or operable program.
    Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
    At line:1 char:1
    + popy_run
    + ~~~~~~~~
        + CategoryInfo          : ObjectNotFound: (popy_run:String) [], CommandNotFoundException
        + FullyQualifiedErrorId : CommandNotFoundException

Cause
~~~~~~~

|popy| is either not installed or your system path is not configured correctly.


Solution
~~~~~~~~~
    
In a |psp| type:-

.. code-block:: ps1con

    $ $env:Path
 
In order for |popy| to work the directory containing 'popy_env.bat' on your machine, needs to be listed in the |windoze| system path. If the 'popy_env.bat' directory is |not| present, then you need to manually add it. In a |psp| prompt you can do this:-

.. code-block:: ps1con

    $ $env:Path = "$env:Path;c:\PoPy"
    
Where 'c:\\PoPy' is the recommended install directory for |popy|.
 
To save the new path permanently do:-

.. code-block:: ps1con

    $ setx PATH $env:Path
 
Note you probably need **admin rights** to use the 'setx' command. Once your |windoze| path is sorted out you should be able to run and test the |popy| environment as follows:-
 
.. code-block:: ps1con
    
    $ popy_env
    $ popy_info

..
    format below + get original message!!!
    is there a code-block: powershell lexer??!?

.. _popy_env_permission_error:
    
'popy_env' permission error
=============================

Scenario
~~~~~~~~~

You start a |psp| and type the following command:-

.. code-block:: ps1con

    $ popy_env

Then you see the message:-

.. code-block:: ps1con

    popy_env : File C:\PoPy\popy_env.ps1 cannot be loaded because running scripts is disabled on
    this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
    At line:1 char:1
    + popy_env
    + ~~~~~~~~
        + CategoryInfo          : SecurityError: (:) [], PSSecurityException
        + FullyQualifiedErrorId : UnauthorizedAccess

Cause
~~~~~~~

You do not have sufficient Powershell script execution rights to run the :ref:`popy_env` setup script.

Solution1
~~~~~~~~~~

If you are an Administrator on your |windoze| system, you may grant execution rights to all powershell scripts, by opening a **Administrator** |psp| and running this command:-

.. code-block:: ps1con

    $ set-ExecutionPolicy unrestricted

Or possibly just set the execution policy for the :ref:`popy_env` script alone:-

.. code-block:: ps1con

    $ set-ExecutionPolicy ByPass -File c:\PoPy\popy_env.ps1
    
This should then allow you to run:-

.. code-block:: ps1con

    $ popy_env

From a normal **non-admin** |psp|.

For more information on the Powershell script permission system see this page:-

https://docs.microsoft.com/en-gb/powershell/module/microsoft.powershell.core/about/about_execution_policies
 
Solution2
~~~~~~~~~~
 
An alternative solution maybe to :ref:`uninstall_popy` and reinstall |popy| in a location where your |windoze| user has more permissions. It's a good idea to **avoid** folders like:-

.. code-block:: console
    
    c:\Program Files\PoPy
    
We recommend this directory, if you want non-admin users to run |popy|:-

.. code-block:: console
    
    c:\PoPy
    
For more information see :ref:`install_popy` 

Solution3
~~~~~~~~~~

You could invoke :ref:`popy_env` from a |dosp| instead and just |not| use Powershell. For example start |popy| using :ref:`windows_shortcut_method`.

