NationalSecurityAgency/ghidra · error · IllegalStateException

AddressRange requires a trace for context

Error message

AddressRange requires a trace for context

What it means

Thrown by the default ValueDecoder.toRange when required is true. The default decoder lacks a Trace, so it cannot resolve an AddrRange's address space into a real AddressSpace and cannot build an AddressRange. Only a trace-bound decoder (OpenTrace) can resolve the space and clamp/validate the range.

Source

Thrown at Ghidra/Debug/Debugger-rmi-trace/src/main/java/ghidra/app/plugin/core/debug/service/tracermi/ValueDecoder.java:86

		public Object toValue(Value value) {
			Object obj = ValueDecoder.super.toValue(value);
			if (obj instanceof byte[] va) {
				return NumericUtilities.convertBytesToString(va, ":");
			}
			return obj;
		}
	};

	default Address toAddress(Addr addr, boolean required) {
		if (required) {
			throw new IllegalStateException("Address requires a trace for context");
		}
		return null;
	}

	default AddressRange toRange(AddrRange range, boolean required) {
		if (required) {
			throw new IllegalStateException("AddressRange requires a trace for context");
		}
		return null;
	}

	default Object getObject(ObjSpec spec, boolean required) {
		if (required) {
			throw new IllegalStateException("TraceObject requires a trace for context");
		}
		return null;
	}

	default Object getObject(ObjDesc desc, boolean required) {
		if (required) {
			throw new IllegalStateException("TraceObject requires a trace for context");
		}
		return null;
	}

View on GitHub (pinned to d5f144c24d)

Solutions

1. Use the OpenTrace decoder when you need to resolve ranges, so toRange has the trace's address spaces.
2. Call toRange(range, false) if a range is optional, yielding null instead of an exception.
3. Note ValueDecoder.DISPLAY overrides toRange to synthesize a generic 64-bit space, so use DISPLAY for display-only decoding.

Example fix

// before
ValueDecoder dec = ValueDecoder.DEFAULT;
AddressRange r = dec.toRange(range, true);

// after
ValueDecoder dec = openTrace; // trace-bound
AddressRange r = dec.toRange(range, true);

ValueDecoder dec = (openTrace != null) ? openTrace : ValueDecoder.DEFAULT;
AddressRange r = (openTrace != null) ? dec.toRange(range, true) : null;

boolean hasTraceContext(ValueDecoder dec) {
    return dec instanceof OpenTrace;
}

try {
    return dec.toRange(range, true);
} catch (IllegalStateException e) {
    return null;
}

When it happens

Trigger: Calling toRange(range, true) on ValueDecoder.DEFAULT or any decoder without trace context, when a value requires an AddressRange.

Common situations: Decoding ranges in a trace-less context (display formatting of a message that unexpectedly needs a real range); using the wrong decoder for a value that is a range.

Related errors

• Address requires a trace for context
• TraceObject requires a trace for context
• {object} is not {err_msg}
• Extraneous parameters: {extraneous}
• Type errors: {typeErrors}

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