{"record":{"id":"7bb111bef23594f9","repo":"NationalSecurityAgency/ghidra","slug":"invalid-address-space-for-overlay","errorCode":null,"errorMessage":"Invalid address space for overlay: {}","messagePattern":"Invalid address space for overlay: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/address/DBTraceOverlaySpaceAdapter.java","lineNumber":255,"sourceCode":"\t\tfactory.refreshStaleOverlayStatus();\n\t}\n\n\tprivate boolean isCompatibleOverlay(ProgramOverlayAddressSpace os, DBTraceOverlaySpaceEntry ent,\n\t\t\tProgramAddressFactory factory) {\n\t\tAddressSpace baseSpace = factory.getAddressSpace(ent.baseSpace);\n\t\tif (baseSpace == null) {\n\t\t\t// Error condition should be handled better - language may have dropped original base space\n\t\t\tthrow new RuntimeException(\"Base space for overlay not found: \" + ent.baseSpace);\n\t\t}\n\t\treturn baseSpace == os.getOverlayedSpace();\n\t}\n\n\tprotected AddressSpace doCreateOverlaySpace(String name, AddressSpace base)\n\t\t\tthrows DuplicateNameException {\n\t\tTraceAddressFactory factory = trace.getInternalAddressFactory();\n\n\t\tif (!factory.isValidOverlayBaseSpace(base)) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\"Invalid address space for overlay: \" + base.getName());\n\t\t}\n\n\t\tif (factory.getAddressSpace(name) != null) {\n\t\t\tthrow new DuplicateNameException(\n\t\t\t\t\"Overlay space '\" + name + \"' duplicates name of another address space\");\n\t\t}\n\n\t\tDBTraceOverlaySpaceEntry ent = overlayStore.create();\n\t\tProgramOverlayAddressSpace space = factory.addOverlaySpace(ent.getKey(), name, base);\n\n\t\t// Only if it succeeds do we store the record\n\t\tent.set(space.getName(), base.getName());\n\t\ttrace.updateViewsAddSpaceBlock(space);\n\t\ttrace.setChanged(\n\t\t\tnew TraceChangeRecord<>(TraceEvents.OVERLAY_ADDED, space, trace, null, space));\n\t\treturn space;\n\t}","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/address/DBTraceOverlaySpaceAdapter.java#L237-L273","documentation":"doCreateOverlaySpace validates the proposed base address space via factory.isValidOverlayBaseSpace(base). If false, it throws IllegalArgumentException(\"Invalid address space for overlay\"). This enforces the invariant that overlays sit on real physical memory spaces: an overlay space, register space, constant space, or other non-physical space is rejected as a base.","triggerScenarios":"Calling createOverlayAddressSpace / getOrCreateOverlayAddressSpace / doCreateOverlaySpace passing an overlay space (e.g. the result of a previous create), a register space, a constant space, or another non-physical space as base.","commonSituations":"Programmatic batch overlay creation accidentally chaining the returned overlay as the next base; mistaking a register-mapped or constant space for a memory space; passing a space obtained from an address without resolving its physical space.","solutions":["Pass a physical memory address space from the base address factory.","Derive the base from a real address: addr.getAddressSpace().getPhysicalSpace().","Pre-check with factory.isValidOverlayBaseSpace(base) and skip/handle when false."],"exampleFix":"// before\nAddressSpace base = someOverlayAddr.getAddressSpace();\ntrace.createOverlayAddressSpace(\"ovl\", base);\n\n// after\nAddressSpace base = someAddr.getAddressSpace().getPhysicalSpace();\nif (!factory.isValidOverlayBaseSpace(base)) {\n    throw new IllegalStateException(\"not a valid overlay base\");\n}\ntrace.createOverlayAddressSpace(\"ovl\", base);","handlingStrategy":"validation","validationCode":"AddressSpace base = addr.getAddressSpace().getPhysicalSpace();\nif (!factory.isValidOverlayBaseSpace(base)) {\n    // not a valid overlay base; do not call createOverlayAddressSpace\n}","typeGuard":"static boolean isOverlayBaseOk(TraceAddressFactory f, AddressSpace s) {\n    return s != null && f.isValidOverlayBaseSpace(s);\n}","tryCatchPattern":null,"preventionTips":["Always resolve the physical space before using it as an overlay base.","Never chain the result of createOverlayAddressSpace as the base of another overlay.","Validate with isValidOverlayBaseSpace at the boundary of any user-driven overlay creation."],"tags":["overlay","validation","address-space"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}