What causes "Section path must be a successor of this module's path" in NationalSecurityAgency/ghidra?

Build the section path by appending the section key to the module's canonical path: module.getCanonicalPath().key(sectionKey) or equivalent path-builder API.

NationalSecurityAgency/ghidra · error · IllegalArgumentException

Section path must be a successor of this module's path

Error message

Section path must be a successor of this module's path

What it means

Thrown by DBTraceModule.addSection when the provided sectionPath (parsed as a KeyPath) is not a descendant (successor) of the module's canonical path in the trace object tree. Ghidra traces organize modules and sections as objects in a path hierarchy, so a section must live underneath its parent module's key path.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/module/DBTraceModule.java:103

	public DBTraceModule(DBTraceObject object) {
		this.object = object;

		translator = new ModuleChangeTranslator(object, this);
	}

	@Override
	public Trace getTrace() {
		return object.getTrace();
	}

	@Override
	public TraceSection addSection(long snap, String sectionPath, String sectionName,
			AddressRange range) throws DuplicateNameException {
		try (LockHold hold = object.getTrace().lockWrite()) {
			DBTraceObjectManager manager = object.getManager();
			KeyPath sectionKeyList = KeyPath.parse(sectionPath);
			if (!object.getCanonicalPath().isAncestor(sectionKeyList)) {
				throw new IllegalArgumentException(
					"Section path must be a successor of this module's path");
			}
			return manager.addSection(sectionPath, sectionName, Lifespan.nowOn(snap), range);
		}
	}

	@Override
	public String getPath() {
		return object.getCanonicalPath().toString();
	}

	@Override
	public void setName(Lifespan lifespan, String name) {
		object.setValue(lifespan, KEY_MODULE_NAME, name);
	}

	@Override
	public void setName(long snap, String name) {

View on GitHub (pinned to d5f144c24d)

Solutions

Build the section path by appending the section key to the module's canonical path: module.getCanonicalPath().key(sectionKey) or equivalent path-builder API.
Verify with object.getCanonicalPath().isAncestor(KeyPath.parse(sectionPath)) before calling addSection.
Use the module's getPath() to derive the prefix instead of hardcoding the path string.

Example fix

// before
String sectionPath = "Sections[]/0";
module.addSection(snap, sectionPath, ".text", range);

// after
KeyPath basePath = module.getObject().getCanonicalPath();
String sectionPath = basePath.key("Sections[]").index(0).toString();
module.addSection(snap, sectionPath, ".text", range);

Defensive patterns

Strategy: validation

Validate before calling

// Verify the section path is a descendant of the module's path before addSection
KeyPath modulePath = module.getObject().getCanonicalPath();
KeyPath sectionPath = KeyPath.parse(sectionPathStr);
if (!modulePath.isAncestor(sectionPath)) {
    sectionPathStr = modulePath.key("Sections[]").index(0).toString();
}
module.addSection(snap, sectionPathStr, name, range);

Prevention

Always derive section paths from the module's canonical path, never hardcode them.
Validate isAncestor before calling addSection.
Use the path-builder API to append section keys rather than string concatenation.

When it happens

Trigger: Calling addSection(snap, sectionPath, sectionName, range) where sectionPath does not start with / is a child of the module's own canonical path. For example the module is at 'Modules[1]' but sectionPath is 'OtherModule[]/Sections[0]' or a top-level key.

Common situations: Constructing section paths manually with string concatenation and getting the parent prefix wrong. Copying a section path from one module and reusing it on another module without adjusting the prefix. Misunderstanding the KeyPath convention (e.g. omitting the module key segment).

Related errors

AI-assisted analysis of NationalSecurityAgency/ghidra@d5f144c24d (2026-08-14). Data as JSON: /api/errors/d5769332114c8d75. Report an issue: GitHub.