# Debug TEN applications (/en/ai/ten-agent/develop/debug-ten-applications)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

The TEN Framework supports debugging applications built with multiple programming languages, including C++, Go, and Python. This guide shows you how to configure VS Code to debug your TEN applications effectively, whether you are working with single-language or mixed-language projects.

## Debug use cases [#debug-use-cases]

There are two main use cases when debugging TEN applications. You can use VS Code's debugging capabilities with language-specific debuggers and custom launch configurations for both:

**Framework development**
When contributing to or modifying the TEN Framework itself, use the `launch.json` file available in the framework's source tree. This file provides default debug targets to help you get started quickly.

**Application development**
When building your own applications using the TEN Framework, add custom configurations to your `.vscode/launch.json` file. This enables you to set breakpoints and inspect variables, regardless of the programming language you use: C++, Go, or Python.

Both use cases provide breakpoint debugging, variable inspection, and step-through execution capabilities.

## Application development [#application-development]

When developing your own application based on the TEN Framework using VS Code, add custom configurations to your `.vscode/launch.json` file. This enables you to set breakpoints and inspect variables, regardless of the programming language you use: C++, Go, or Python.

### C++ applications [#c-applications]

When you write your application in C++, you can write extensions in either C++ or Python.

#### Debug C++ code with lldb or gdb [#debug-c-code-with-lldb-or-gdb]

Use the following configurations to debug C++ code:

* **With lldb:**

  ```json
  {
    "name": "app (C++) (lldb, launch)",
    "type": "lldb",
    "request": "launch", // "launch" or "attach"
    "program": "${workspaceFolder}/bin/worker", // The executable path
    "cwd": "${workspaceFolder}/",
    "env": {
      "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
      "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib" // macOS
    }
  }
  ```

* **With gdb:**

  ```json
  {
    "name": "app (C++) (gdb, launch)",
    "type": "cppdbg",
    "request": "launch", // "launch" or "attach"
    "program": "${workspaceFolder}/bin/worker", // The executable path
    "cwd": "${workspaceFolder}/",
    "MIMode": "gdb",
    "environment": [
      {
        // linux
        "name": "LD_LIBRARY_PATH",
        "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
      },
      {
        // macOS
        "name": "DYLD_LIBRARY_PATH",
        "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
      }
    ]
  }
  ```

#### Debug Python code with debugpy [#debug-python-code-with-debugpy]

Use `debugpy` to debug Python code in TEN applications. Since TEN applications run Python code inside an embedded interpreter rather than starting with the Python interpreter directly, you must attach the debugger to the running process instead of launching it directly.

1. Install `debugpy` in the Python environment:

   ```bash
   pip install debugpy
   ```

2. Set the `TEN_ENABLE_PYTHON_DEBUG` and `TEN_PYTHON_DEBUG_PORT` environment variables before starting the application:

   ```bash
   TEN_ENABLE_PYTHON_DEBUG=true TEN_PYTHON_DEBUG_PORT=5678 ./bin/worker
   ```

   When you set `TEN_ENABLE_PYTHON_DEBUG` to `true`, the application blocks until a debugger is attached. When you set `TEN_PYTHON_DEBUG_PORT`, the debugger server listens on the specified port for incoming connections.

3. After starting the application, attach the debugger to the running process using the following configuration:

   ```json
   {
     "name": "app (C++) (debugpy, attach)",
     "type": "debugpy",
     "request": "attach",
     "connect": {
       "host": "localhost",
       "port": 5678
     },
     "justMyCode": false
   }
   ```

#### Debug C++ and Python code simultaneously [#debug-c-and-python-code-simultaneously]

To debug C++ and Python code simultaneously with one click in VS Code:

1. Define a delay task before attaching the debugger:

   ```json
   {
     "label": "delay 3 seconds",
     "type": "shell",
     "command": "sleep 3",
     "windows": {
       "command": "ping 127.0.0.1 -n 3 > nul"
     },
     "group": "none"
   }
   ```

2. Add the following configurations to the `launch.json` file:

   ```json
   "configurations": [
       {
           "name": "app (C++) (lldb, launch with debugpy)",
           "type": "lldb",
           "request": "launch", // "launch" or "attach"
           "program": "${workspaceFolder}/bin/worker", // The executable path
           "cwd": "${workspaceFolder}/",
           "env": {
               "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
               "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // macOS
               "TEN_ENABLE_PYTHON_DEBUG": "true",
               "TEN_PYTHON_DEBUG_PORT": "5678"
           }
       },
       {
           "name": "app (C++) (debugpy, attach with delay)",
           "type": "debugpy",
           "request": "attach",
           "connect": {
               "host": "localhost",
               "port": 5678
           },
           "justMyCode": false,
           "preLaunchTask": "delay 3 seconds"
       }
   ],
   "compounds": [
       {
           "name": "app (C++) (lldb, launch) and app (C++) (debugpy, attach)",
           "configurations": [
               "app (C++) (lldb, launch with debugpy)",
               "app (C++) (debugpy, attach with delay)"
           ]
       }
   ]
   ```

3. Start debugging by selecting the compound configuration `app (C++) (lldb, launch) and app (C++) (debugpy, attach)`.

### Go applications [#go-applications]

When you write your application in Go, you can write extensions in either Go or Python.

#### Debug Go code with delve [#debug-go-code-with-delve]

Use the following configuration to debug your Go extensions:

```json
{
  "name": "app (golang) (go, launch)",
  "type": "go",
  "request": "launch",
  "mode": "exec",
  "cwd": "${workspaceFolder}/",
  "program": "${workspaceFolder}/bin/worker", // The executable path
  "env": {
    "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
    "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // macOS
    "TEN_APP_BASE_DIR": "${workspaceFolder}"
  }
}
```

#### Debug C++ extensions with lldb or gdb [#debug-c-extensions-with-lldb-or-gdb]

Use the following configurations to debug C++ extensions in your Go application:

* **With lldb:**

  ```json
  {
    "name": "app (Go) (lldb, launch)",
    "type": "lldb",
    "request": "launch", // "launch" or "attach"
    "program": "${workspaceFolder}/bin/worker", // The executable path
    "cwd": "${workspaceFolder}/",
    "env": {
      "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
      "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib" // macOS
    },
    "initCommands": ["process handle SIGURG --stop false --pass true"]
  }
  ```

* **With gdb:**

  ```json
  {
    "name": "app (Go) (gdb, launch)",
    "type": "cppdbg",
    "request": "launch", // "launch" or "attach"
    "program": "${workspaceFolder}/bin/worker", // The executable path
    "cwd": "${workspaceFolder}/",
    "MIMode": "gdb",
    "environment": [
      {
        // linux
        "name": "LD_LIBRARY_PATH",
        "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
      },
      {
        // macOS
        "name": "DYLD_LIBRARY_PATH",
        "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
      }
    ]
  }
  ```

#### Debug Python code with debugpy [#debug-python-code-with-debugpy-1]

For Python debugging setup, refer to the C++ applications section. Set the environment variables `TEN_ENABLE_PYTHON_DEBUG` and `TEN_PYTHON_DEBUG_PORT` before starting the application:

```bash
TEN_ENABLE_PYTHON_DEBUG=true TEN_PYTHON_DEBUG_PORT=5678 ./bin/worker
```

Attach the debugger to the running process using the following configuration:

```json
{
  "name": "app (Go) (debugpy, attach)",
  "type": "debugpy",
  "request": "attach",
  "connect": {
    "host": "localhost",
    "port": 5678
  },
  "justMyCode": false
}
```

#### Debug multiple languages simultaneously [#debug-multiple-languages-simultaneously]

To debug C++, Go, and Python code simultaneously with one click in VS Code:

1. Define a delay task before attaching the debugger:

   ```json
   {
     "label": "delay 3 seconds",
     "type": "shell",
     "command": "sleep 3",
     "windows": {
       "command": "ping 127.0.0.1 -n 3 > nul"
     },
     "group": "none"
   }
   ```

2. Add the following configurations to the `launch.json` file:

   ```json
   "configurations": [
       {
           "name": "app (golang) (debugpy, remote attach with delay)",
           "type": "debugpy",
           "request": "attach",
           "connect": {
               "host": "localhost",
               "port": 5678
           },
           "preLaunchTask": "delay 3 seconds",
           "justMyCode": false
       },
       {
           "name": "app (golang) (go, launch with debugpy)",
           "type": "go",
           "request": "launch",
           "mode": "exec",
           "cwd": "${workspaceFolder}/",
           "program": "${workspaceFolder}/bin/worker",
           "env": {
               "TEN_APP_BASE_DIR": "${workspaceFolder}",
               "TEN_ENABLE_PYTHON_DEBUG": "true",
               "TEN_PYTHON_DEBUG_PORT": "5678"
           }
       },
       {
           "name": "app (golang) (lldb, launch with debugpy)",
           "type": "lldb",
           "request": "launch",
           "program": "${workspaceFolder}/bin/worker",
           "cwd": "${workspaceFolder}/",
           "env": {
               "TEN_ENABLE_PYTHON_DEBUG": "true",
               "TEN_PYTHON_DEBUG_PORT": "5678"
           },
           "initCommands": [
               "process handle SIGURG --stop false --pass true"
           ]
       }
   ],
   "compounds": [
       {
           "name": "Mixed Go/Python",
           "configurations": [
               "app (golang) (go, launch with debugpy)",
               "app (golang) (debugpy, remote attach with delay)"
           ]
       },
       {
           "name": "Mixed Go/Python/C++ (lldb)",
           "configurations": [
               "app (golang) (lldb, launch with debugpy)",
               "app (golang) (debugpy, remote attach with delay)"
           ]
       }
   ]
   ```

**Use compound configurations:**

* For C++ and Python debugging: Use `Mixed Go/Python/C++ (lldb)`. This supports breakpoint debugging for all three languages, but variable inspection only works for C++ and Python.
* For Go and Python debugging: Use `Mixed Go/Python`. This supports both breakpoint debugging and variable inspection for Go and Python.

### Python applications [#python-applications]

When you write your application in Python, you can write extensions in either Python or C++.

#### Debug C++ extensions with lldb or gdb [#debug-c-extensions-with-lldb-or-gdb-1]

Use the following configuration to debug C++ extensions in your Python application:

```json
{
  "name": "app (Python) (cpp, launch)",
  "type": "cppdbg",
  "request": "launch", // "launch" or "attach"
  "program": "/usr/bin/python3", // The Python interpreter path
  "args": ["main.py"],
  "cwd": "${workspaceFolder}/",
  "environment": [
    {
      "name": "PYTHONPATH",
      "value": "${workspaceFolder}/ten_packages/system/ten_runtime_python/lib:${workspaceFolder}/ten_packages/system/ten_runtime_python/interface"
    },
    {
      "name": "TEN_APP_BASE_DIR",
      "value": "${workspaceFolder}/"
    }
  ],
  "MIMode": "gdb" // "gdb" or "lldb"
}
```

#### Debug Python code with debugpy [#debug-python-code-with-debugpy-2]

Use the following configuration to debug Python code directly:

```json
{
  "name": "app (Python) (debugpy, launch)",
  "type": "debugpy",
  "python": "/usr/bin/python3",
  "request": "launch",
  "program": "${workspaceFolder}/main.py",
  "console": "integratedTerminal",
  "cwd": "${workspaceFolder}/",
  "env": {
    "PYTHONPATH": "${workspaceFolder}/ten_packages/system/ten_runtime_python/lib:${workspaceFolder}/ten_packages/system/ten_runtime_python/interface",
    "TEN_APP_BASE_DIR": "${workspaceFolder}/",
    "TEN_ENABLE_PYTHON_DEBUG": "true"
  }
}
```

#### Debug C++ and Python code simultaneously [#debug-c-and-python-code-simultaneously-1]

To debug both C++ and Python code simultaneously:

1. Launch the application with the `app (Python) (debugpy, launch)` configuration
2. Attach the C++ debugger to the running process using the following configuration:

   ```json
   {
     "name": "app (Python) (cpp, attach)",
     "type": "cppdbg",
     "request": "attach", // "launch" or "attach"
     "program": "${workspaceFolder}/bin/worker", // The executable path
     "cwd": "${workspaceFolder}/",
     "MIMode": "gdb",
     "environment": [
       {
         "name": "LD_LIBRARY_PATH",
         "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
       },
       {
         "name": "DYLD_LIBRARY_PATH",
         "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
       }
     ]
   }
   ```