Mozdebug Library

Common errors

• ConnectionRefusedError: [Errno 111] Connection refused

  cause The `MozDebugClient` failed to connect because no debug server was running or listening at the specified host and port, or a firewall blocked the connection.
  fix Ensure a debug server (e.g., `rr replay -s 9000` or `gdbserver host:port program`) is active and listening on the target host/port before running your `mozdebug` client script. Check firewall rules if the server is remote.

• ModuleNotFoundError: No module named 'mozdebug'

  cause The `mozdebug` library is not installed in the active Python environment, or the script is being run with a different Python interpreter than where it was installed.
  fix Install the library using `pip install mozdebug`. If using a virtual environment, ensure it is activated before installation and execution.

• AttributeError: 'MozDebugClient' object has no attribute 'some_nonexistent_method'

  cause Attempting to call a method or access an attribute that does not exist on the `MozDebugClient` instance, or has been renamed in the installed version.
  fix Consult the official `mozdebug` source code on GitHub or any available documentation for the correct API methods and their signatures for your installed version (0.4.0).

Warnings

• gotcha The `mozdebug` library is a client-side tool; it does not launch or manage the debuggee process or the debugger itself. You must ensure a compatible debug server (e.g., `rr`, `gdbserver` with specific configurations) is already running and listening on the target host/port before the `MozDebugClient` can connect.
  Fix: Launch your debug server process manually before attempting to connect with `MozDebugClient`.
• gotcha Mozdebug implements Mozilla's custom debugging protocol, which is distinct from standard GDB or LLDB remote protocols. It may not be compatible with generic debug servers without specific bridging or shim layers designed for this protocol.
  Fix: Verify that your debug server or target application is configured to expose the Mozilla debugging protocol, or use a tool specifically designed to interoperate with `mozdebug`.

Install

• pip install mozdebug Install latest version

Imports

• MozDebugClient

  from mozdebug.client import MozDebugClient

• SymbolFetcher

  from mozdebug.symbols import SymbolFetcher

Quickstart

This quickstart demonstrates how to instantiate and attempt to connect a `MozDebugClient` to a running debug server. It includes basic error handling for a `ConnectionRefusedError`, which is common if no server is active. Ensure a debug server compatible with Mozilla's protocol is running at the specified host and port for a successful connection.

import os
from mozdebug.client import MozDebugClient

# In a real scenario, you would launch a debug server (e.g., rr, gdbserver)
# and configure it to listen on a host/port, then connect to it.
# This example just demonstrates the client instantiation and connection attempt.
# A ConnectionRefusedError is expected if no server is running at the specified address.

try:
    # Attempt to connect to a debug server.
    # Replace 'localhost' and 9000 with your server's actual host and port.
    client = MozDebugClient(host=os.environ.get('DEBUG_SERVER_HOST', 'localhost'),
                           port=int(os.environ.get('DEBUG_SERVER_PORT', 9000)))
    print(f"Attempting to connect to {client.host}:{client.port}...")
    client.connect()
    print("Successfully connected to debug server.")

    # In a real application, you would now interact with the debug client, e.g.,
    # client.attach_to_process(pid), client.continue_execution(), client.get_stack().

    # Example: Disconnect
    client.disconnect()
    print("Disconnected.")

except ConnectionRefusedError:
    print("Could not connect to the debug server. Ensure a debug server (e.g., rr, gdbserver) is running and listening on the specified host/port.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")