Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Debug TEN applications

Updated

Configure VS Code to debug TEN Framework applications and extensions written in C++, Go, and Python.

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

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

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

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

Debug C++ code with lldb or gdb

Use the following configurations to debug C++ code:

  • With lldb:

    {
  "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:

    {
  "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

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:

    pip install debugpy

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

    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:

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

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:

    {
  "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:

    "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

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

Debug Go code with delve

Use the following configuration to debug your Go extensions:

{
  "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

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

  • With lldb:

    {
  "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:

    {
  "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

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:

TEN_ENABLE_PYTHON_DEBUG=true TEN_PYTHON_DEBUG_PORT=5678 ./bin/worker

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

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

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:

    {
  "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:

    "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

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

Debug C++ extensions with lldb or gdb

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

{
  "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

Use the following configuration to debug Python code directly:

{
  "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

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:

    {
  "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"
    }
  ]
}

Was this page helpful?

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved