{"record":{"id":"66371ec21c6e959b","repo":"NationalSecurityAgency/ghidra","slug":"base-space-for-overlay-not-found","errorCode":null,"errorMessage":"Base space for overlay not found: {}","messagePattern":"Base space for overlay not found: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/address/DBTraceOverlaySpaceAdapter.java","lineNumber":245,"sourceCode":"\t\t\t\tDBTraceOverlaySpaceEntry ent = keyToRecordMap.get(key);\n\t\t\t\tString spaceName = ent.name;\n\t\t\t\tAddressSpace baseSpace = factory.getAddressSpace(ent.baseSpace);\n\t\t\t\tfactory.addOverlaySpace(key, spaceName, baseSpace);\n\t\t\t}\n\t\t}\n\t\tcatch (IllegalArgumentException | DuplicateNameException e) {\n\t\t\tthrow new AssertionError(\"Unexpected error updating overlay address spaces\", e);\n\t\t}\n\n\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","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/NationalSecurityAgency/ghidra/blob/d5f144c24d6bc53c9cbf4448c6d11143e7696206/Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/database/address/DBTraceOverlaySpaceAdapter.java#L227-L263","documentation":"isCompatibleOverlay reads a stored DBTraceOverlaySpaceEntry and resolves its baseSpace name through the program address factory. If factory.getAddressSpace(ent.baseSpace) returns null, the stored overlay references an address space that no longer exists in the (possibly updated) processor language, and a RuntimeException is thrown. The inline comment admits this should be handled better. It is a data-integrity failure surfaced while opening or migrating a trace.","triggerScenarios":"Opening a saved trace after the underlying processor language definition changed and dropped/renamed the base address space an overlay was built on; the DB refresh/load path calling isCompatibleOverlay during open; cross-version trace migration where the new language pack lacks the original base space.","commonSituations":"Upgrading Ghidra or processor-language definitions between versions; importing a trace from another install with different language packs; manually editing or partially corrupting the trace DB.","solutions":["Install/register the same processor language (with the original base space name) that was present when the trace was created.","Re-open the trace on the original Ghidra/language configuration that produced it.","If the space is genuinely gone, treat the trace as needing repair: recreate the overlay against a space that still exists, or rebuild the trace."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before opening, confirm every stored overlay's base space still resolves\nfor (String base : storedOverlayBaseSpaces) {\n    if (factory.getAddressSpace(base) == null) {\n        // abort open or migrate: missing language space\n    }\n}","typeGuard":null,"tryCatchPattern":"try { trace.open(...); }\ncatch (RuntimeException e) {\n    if (e.getMessage().startsWith(\"Base space for overlay not found\")) { /* require original language */ }\n    else throw e;\n}","preventionTips":["Keep the processor language module installed across open/save cycles.","Avoid opening traces on installs missing the originating language pack.","Treat overlay/base-space drift during upgrade as a migration step, not a silent skip."],"tags":["overlay","corruption","address-space","language-version"],"backgroundTag":null,"analyzedSha":"d5f144c24d6bc53c9cbf4448c6d11143e7696206","analyzedAt":"2026-08-14T01:00:57.564Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}