<type>documentation</type>
<domain>trouble</domain>
<id>trouble-debug-start</id>
<title>Failure to Start Debug</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

Use the following steps to diagnose failure to start debugging:

**Try a simple test case** using the following code in a new Python file and
``Step Into`` in the ``Debug`` menu:

.. python::

  print("test1")
  print("test2")

This rules out unexpectedly running to completion or running into a fatal error after
debug has started successfully.

**Set WINGDB_PRINT_ALL_TRACEBACKS=1** in the ``Environment`` in `Project Properties
<ref:proj/project-properties>`__ and try restarting the ``Python Shell``
from its ``Options`` menu.  This is often a simple way to obtain a traceback that
shows why Python is failing to start.

**Verify that your Python version is supported** according to `Supported Python
Versions <ref:install/supported-python-versions>`__.  If not, you may need a different
version of Wing.
~~~if WEBSITE:
Note that you must use ``Wing Manual`` in the IDE's ``Help`` menu to see the correct 
information for your version of Wing.
~~~

**Check that Python Path is valid** with ``Show Python Environment`` in the ``Source``
menu. If this contains directories inside a Python version that doesn't match the
interpreter being run for the debug process, then Python will fail to start. You can set
``Python Path`` and ``Python Executable`` in `Project Properties
<ref:proj/project-properties>`__.
   
**Check for malfunctions of Activate Env** entered for ``Python Executable`` under the
``Environment`` tab of ``Project Properties``. If activating the environment is failing,
you may be able to work around the problem by selecting ``Command Line`` instead and
entering the full path to the ``python`` or ``python.exe`` in your environment.

**Check for environment conflicts**, which may occur if you set the ``PYTHONHOME`` or
``PYTHONPATH`` environment variables and they do not match the particular Python
interpreter that Wing is launching.

**Completely remove and reinstall Python** if you have installed a newer version over and
older one on disk, in the same directory. This may cause debugging to fail even if other
Python programs appear to work with the Python installation because the debugger used
functionality that isn't used by most other code.

**Confirm that TCP/IP is working on your machine** since Wing's debugger uses TCP/IP to
communicate with the IDE.

**Disable PyGame full-screen mode** and use window mode instead, since full-screen mode
does not work with Python debuggers.

**In other cases, collect diagnostics** as described in `Diagnostic Output
<ref:install/trouble-diagnostic>`__.

