NationalSecurityAgency/ghidra · error · IllegalArgumentException

Time specification must have form 'snap[:steps[.pSteps]]'

Error message

Time specification must have form 'snap[:steps[.pSteps]]'

What it means

TraceSchedule.parse splits the spec on ':' and tries to decode the first part (the snapshot index) as a number. If that fails with NumberFormatException, the generic parse error message is thrown, wrapping the cause. The snapshot must be a valid integer in the given radix.

Source

Thrown at Ghidra/Debug/Framework-TraceModeling/src/main/java/ghidra/trace/model/time/schedule/TraceSchedule.java:275

	 * 
	 * @param spec the string specification
	 * @param source the presumed source of the schedule
	 * @param radix the radix
	 * @return the parsed schedule
	 */
	public static TraceSchedule parse(String spec, Source source, TimeRadix radix) {
		String[] parts = spec.split(":", 2);
		if (parts.length > 2) {
			throw new AssertionError();
		}
		final long snap;
		final Sequence ticks;
		final Sequence pTicks;
		try {
			snap = radix.decode(parts[0]);
		}
		catch (NumberFormatException e) {
			throw new IllegalArgumentException(PARSE_ERR_MSG, e);
		}
		if (parts.length > 1) {
			String[] subs = parts[1].split("\\.");
			try {
				ticks = Sequence.parse(subs[0], radix);
			}
			catch (IllegalArgumentException e) {
				throw new IllegalArgumentException(PARSE_ERR_MSG, e);
			}
			if (subs.length == 1) {
				pTicks = new Sequence();
			}
			else if (subs.length == 2) {
				try {
					pTicks = Sequence.parse(subs[1], radix);
				}
				catch (IllegalArgumentException e) {
					throw new IllegalArgumentException(PARSE_ERR_MSG, e);

View on GitHub (pinned to d5f144c24d)

Solutions

1. Ensure the snapshot portion (before ':') is a valid integer in the given radix
2. If using hex, pass TimeRadix.HEX_LOWER or HEX_UPPER: TraceSchedule.parse(spec, source, TimeRadix.HEX_LOWER)
3. Validate the full spec format with a regex before parsing
4. Use TraceSchedule.snap(snapIndex) for snapshot-only schedules to avoid string parsing

Example fix

// before
TraceSchedule.parse("ff:t1-5", Source.ABNORMAL, TimeRadix.DEC);
// after
TraceSchedule.parse("ff:t1-5", Source.ABNORMAL, TimeRadix.HEX_LOWER);

boolean isValidScheduleSpec(String spec, TimeRadix radix) {
    if (spec == null) return false;
    String[] parts = spec.split(":", 2);
    try {
        radix.decode(parts[0]);
        return true;
    } catch (NumberFormatException e) {
        return false;
    }
}

// N/A

try {
    TraceSchedule schedule = TraceSchedule.parse(spec, source, radix);
} catch (IllegalArgumentException e) {
    // show user the expected format and re-prompt
}

When it happens

Trigger: Calling TraceSchedule.parse with a spec like 'abc:t1-5' or '0x5:t1-5' (with decimal radix), or 'snap:t1-5'. The ':' split produces parts[0]='abc' which cannot be decoded.

Common situations: Using hex-formatted snapshot numbers without switching the radix to HEX. Mistyping the schedule string. Passing an unparsable variable or file content as the schedule. Confusing snapshot names (strings) with snapshot indices (numbers).

Related errors

• Cannot parse tick step: '
• Cannot parse step: '
• Cannot rewind a negative number
• The given prefix (%s) is not actually a prefix of this (%s).
• Cannot parse skip step: '

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