Exceptions

All exceptions in openocd-python inherit from OpenOCDError, allowing callers to catch broadly or narrowly as needed. Import them from the top-level package:

from openocd import (
    OpenOCDError,
    ConnectionError,
    TimeoutError,
    TargetError,
    TargetNotHaltedError,
    FlashError,
    JTAGError,
    SVDError,
    ProcessError,
)
from openocd.breakpoints import BreakpointError

Hierarchy

OpenOCDError
  +-- ConnectionError
  +-- TimeoutError
  +-- TargetError
  |     +-- TargetNotHaltedError
  +-- FlashError
  +-- JTAGError
  +-- SVDError
  +-- ProcessError
  +-- BreakpointError

Note

BreakpointError is defined in openocd.breakpoints rather than openocd.errors, but it still inherits from OpenOCDError. It is not re-exported from the top-level openocd package to avoid a naming collision, so import it directly from openocd.breakpoints.

OpenOCDError

class OpenOCDError(Exception)

Base exception for all openocd-python errors. Catch this to handle any library error in a single clause.

from openocd import OpenOCDError

try:
    async with await Session.connect() as session:
        await session.target.halt()
        data = await session.memory.read_u32(0x0800_0000)
except OpenOCDError as e:
    print(f"Something went wrong: {e}")

ConnectionError

class ConnectionError(OpenOCDError)

Raised when the library cannot establish or maintain a TCP connection to OpenOCD.

When raised:

• Session.connect() or Session.start() cannot reach the TCL RPC port
• The OpenOCD process closes the connection mid-session
• A response exceeds MAX_RESPONSE_SIZE (10 MB) without a separator — likely connected to the wrong port
• The notification socket fails to open

What to check:

• Is OpenOCD running and listening on the expected port?
• Is the host/port correct?
• Is a firewall blocking the connection?

from openocd import ConnectionError

try:
    session = await Session.connect(host="192.168.1.100", port=6666)
except ConnectionError as e:
    print(f"Cannot reach OpenOCD: {e}")

TimeoutError

class TimeoutError(OpenOCDError)

Raised when an operation exceeds its deadline.

When raised:

• Connection attempt times out
• A command does not receive a response within the configured timeout
• OpenOCDProcess.wait_ready() exceeds its timeout waiting for the TCL port to accept connections

from openocd import TimeoutError

try:
    session = await Session.connect(timeout=2.0)
except TimeoutError:
    print("OpenOCD did not respond within 2 seconds")

TargetError

class TargetError(OpenOCDError)

Raised when a target operation fails — the target is not responding or returned an error.

When raised:

• target.halt(), target.resume(), target.step(), or target.reset() fails
• memory.read_*() or memory.write_*() encounters an error response
• registers.read() or registers.write() fails (for reasons other than “not halted”)

from openocd import TargetError

try:
    state = await session.target.halt()
except TargetError as e:
    print(f"Target operation failed: {e}")

TargetNotHaltedError

class TargetNotHaltedError(TargetError)

A specialization of TargetError for operations that require a halted target.

When raised:

• Register reads/writes when the target is still running
• Any operation that OpenOCD rejects with “target not halted”

from openocd import TargetNotHaltedError

try:
    regs = await session.registers.read_all()
except TargetNotHaltedError:
    print("Halt the target before reading registers")
    await session.target.halt()
    regs = await session.registers.read_all()

FlashError

class FlashError(OpenOCDError)

Raised when a flash memory operation fails.

When raised:

• flash.banks() or flash.info() cannot parse OpenOCD output
• flash.read(), flash.write(), flash.erase_sector(), or flash.erase_all() encounters an error
• flash.write_image() fails to program or verify the image
• flash.verify() encounters an error (note: a mismatch returns False rather than raising)
• flash.protect() fails
• flash.erase_sector() receives an invalid sector range (first > last)

from openocd import FlashError

try:
    await session.flash.write_image(Path("firmware.bin"))
except FlashError as e:
    print(f"Flash programming failed: {e}")

JTAGError

class JTAGError(OpenOCDError)

Raised when a JTAG operation fails.

When raised:

• jtag.scan_chain() encounters an error
• jtag.irscan(), jtag.drscan(), or jtag.runtest() fails
• jtag.pathmove() receives an empty state list or an invalid state transition
• jtag.svf() or jtag.xsvf() encounters an error during file execution
• jtag.new_tap() fails

from openocd import JTAGError

try:
    taps = await session.jtag.scan_chain()
except JTAGError as e:
    print(f"JTAG chain error: {e}")

SVDError

class SVDError(OpenOCDError)

Raised when SVD file loading or metadata lookup fails.

When raised:

• svd.load() given a path that does not exist
• svd.load() encounters a parse error in the XML
• svd.list_peripherals() or svd.list_registers() called before load()
• svd.read_register() or svd.decode() references a peripheral or register not in the SVD

from openocd import SVDError

try:
    await session.svd.load(Path("nonexistent.svd"))
except SVDError as e:
    print(f"SVD error: {e}")

ProcessError

class ProcessError(OpenOCDError)

Raised when OpenOCD subprocess management fails.

When raised:

• Session.start() cannot find the openocd binary
• The OpenOCD process exits unexpectedly during startup (error message includes stderr output)
• An empty config string is passed

from openocd import ProcessError

try:
    session = await Session.start("target/stm32f1x.cfg")
except ProcessError as e:
    print(f"OpenOCD failed to start: {e}")

BreakpointError

class BreakpointError(OpenOCDError)

Raised when a breakpoint or watchpoint operation fails. Defined in openocd.breakpoints.

When raised:

• breakpoints.add() or breakpoints.remove() encounters an error (e.g. no HW breakpoints available)
• breakpoints.add_watchpoint() or breakpoints.remove_watchpoint() fails

from openocd.breakpoints import BreakpointError

try:
    await session.breakpoints.add(0x0800_1234, hw=True)
except BreakpointError as e:
    print(f"Breakpoint error: {e}")

Catching at different levels

from openocd import (
    OpenOCDError,
    ConnectionError,
    TargetError,
    TargetNotHaltedError,
)

try:
    async with await Session.connect() as session:
        await session.target.halt()
        pc = await session.registers.pc()
        data = await session.memory.read_u32(pc, 4)

except TargetNotHaltedError:
    # Most specific: target needs to be halted
    print("Target is running -- halt it first")

except TargetError as e:
    # Broader: any target-related failure
    print(f"Target problem: {e}")

except ConnectionError as e:
    # Connection lost
    print(f"Lost connection to OpenOCD: {e}")

except OpenOCDError as e:
    # Catch-all for anything from this library
    print(f"OpenOCD error: {e}")