elsa-workflows/elsa-core · error · BpmnBindingException

BPMN element ' ' declares the timer duration ' ', which is…

Error message

BPMN element '{timer.ElementId}' declares the timer duration '{timer.IsoDuration}', which is not an ISO-8601 duration Elsa can wait for.

What it means

A timer element's duration string must be a valid ISO-8601 duration (e.g. PT5M). This error wraps XmlConvert.ToTimeSpan failing with FormatException, OverflowException, or ArgumentNullException when converting the declared duration to a TimeSpan.

Solutions

  1. Correct the duration to ISO-8601 form: P[nD]T[nH][nM][nS], e.g. PT30S, PT5M, PT1H30M, P1D.
  2. Ensure the prefix is PT for time-only durations (P for days) and units are ordered D, H, M, S.
  3. Validate the string with XmlConvert.ToTimeSpan in a scratch test before re-importing.

Example fix

// before
<bpmn:intermediateCatchEvent id="Wait1"><bpmn:timerEventDefinition><bpmn:timeDuration>5 minutes</bpmn:timeDuration></bpmn:timerEventDefinition></bpmn:intermediateCatchEvent>
// after
<bpmn:intermediateCatchEvent id="Wait1"><bpmn:timerEventDefinition><bpmn:timeDuration>PT5M</bpmn:timeDuration></bpmn:timerEventDefinition></bpmn:intermediateCatchEvent>
Defensive patterns

Strategy: validation

Validate before calling

try { XmlConvert.ToTimeSpan(durationText); }
catch (Exception ex) when (ex is FormatException or OverflowException or ArgumentNullException)
{ throw new InvalidOperationException($"'{durationText}' is not an ISO-8601 duration (e.g. PT5M)."); }

Type guard

static bool IsValidIsoDuration(string? s)
{
    try { XmlConvert.ToTimeSpan(s); return true; }
    catch (Exception e) when (e is FormatException or OverflowException or ArgumentNullException) { return false; }
}

Try / catch

try { await importer.ImportAsync(bpmn); }
catch (BpmnBindingException ex) when (ex.Message.Contains("not an ISO-8601 duration"))
{
    logger.LogError(ex, "Fix the timer duration to ISO-8601 form such as PT5M.");
}

Prevention

When it happens

Trigger: BpmnWorkBinder.IsoDurationOf (called from CreateActivity for a TimerWait binding) calls XmlConvert.ToTimeSpan(timer.IsoDuration) and it throws — the timer's declared duration is null, malformed, or out of range.

Common situations: Writing human formats like '5 minutes' or '5m' instead of 'PT5M'; forgetting the required 'PT' prefix; copying timestamps ('2026-01-01T10:00:00Z') into a duration field.

Understand the failure class

Background: "invalid duration" / "failed to parse duration": why your timeout, interval, or TTL string is rejected and which formats each library accepts — this error's family across 32 libraries.

Related errors

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/f3647c76608f7780. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.Bpmn.Interchange/Binding/BpmnWorkBinder.cs:180

    private static void RefuseUnusedDeclarations(BpmnProcessDefinition definition, ISet<string> consumed)
    {
        foreach (var element in definition.Elements.Where(element => BpmnActivityBindingFormat.Find(element.Extensions) is not null && !consumed.Contains(element.ElementId)))
        {
            throw new BpmnBindingException(
                $"BPMN element '{element.ElementId}' ({element.ElementType}) of process '{definition.ProcessId}' carries an <{BpmnActivityBindingFormat.NamespacePrefix}:{BpmnActivityBindingFormat.BindingElementName}> element, but its work is not an unbound task, so nothing would ever run it. "
                + "Only a task the document describes without implementing takes an authored activity binding.");
        }
    }

    private static TimeSpan IsoDurationOf(BpmnWorkBinding.TimerWait timer)
    {
        try
        {
            return XmlConvert.ToTimeSpan(timer.IsoDuration);
        }
        catch (Exception exception) when (exception is FormatException or OverflowException or ArgumentNullException)
        {
            throw new BpmnBindingException($"BPMN element '{timer.ElementId}' declares the timer duration '{timer.IsoDuration}', which is not an ISO-8601 duration Elsa can wait for.");
        }
    }

    private static string CalledElementOf(BpmnWorkBinding.CallProcess call) =>
        !string.IsNullOrWhiteSpace(call.CalledElement)
            ? call.CalledElement
            : throw new BpmnBindingException($"BPMN element '{call.ElementId}' is a call activity that names no calledElement, so there is no workflow definition to dispatch.");
}

View on GitHub (pinned to fe9217bdfa)