conductor-oss/conductor · error · IllegalArgumentException

on_text_mention requires text

Error message

on_text_mention requires text

What it means

Thrown when a SWARM handoff of type 'on_text_mention' has a null or blank 'text' field. The text field defines the substring that, when found in the conversation, triggers the handoff to the target agent. Without it the handoff condition is undefined.

Source

Thrown at agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/MultiAgentCompiler.java:1505

                    || !Set.of("on_tool_result", "on_text_mention", "on_condition")
                            .contains(handoff.getType())) {
                throw new IllegalArgumentException(
                        "SWARM handoff type must be on_tool_result, on_text_mention, or on_condition");
            }
            if (handoff.getTarget() == null || !targets.contains(handoff.getTarget())) {
                throw new IllegalArgumentException(
                        "SWARM handoff target must name a swarm agent: " + handoff.getTarget());
            }
            switch (handoff.getType()) {
                case "on_tool_result" -> {
                    if (isBlank(handoff.getToolName()) || isBlank(handoff.getResultContains())) {
                        throw new IllegalArgumentException(
                                "on_tool_result requires toolName and resultContains");
                    }
                }
                case "on_text_mention" -> {
                    if (isBlank(handoff.getText())) {
                        throw new IllegalArgumentException("on_text_mention requires text");
                    }
                }
                case "on_condition" -> {
                    if (isBlank(handoff.getTaskName())) {
                        throw new IllegalArgumentException(
                                "on_condition requires a nonblank taskName");
                    }
                }
                default -> throw new IllegalStateException("validated above");
            }
        }
    }

    private static boolean isBlank(String value) {
        return value == null || value.isBlank();
    }

    /**

View on GitHub (pinned to cf7c3e4a8a)

Solutions

  1. Set the handoff's text field to a non-blank string that should trigger the handoff when it appears in conversation.
  2. Choose a text value that won't produce false positives in normal conversation.

Example fix

// before
{"type": "on_text_mention", "target": "billing_agent", "text": ""}
// after
{"type": "on_text_mention", "target": "billing_agent", "text": "I need a refund"}
Defensive patterns

Strategy: validation

Validate before calling

void validateOnTextMention(HandoffConfig h) {
    if ("on_text_mention".equals(h.getType())) {
        if (h.getText() == null || h.getText().isBlank()) {
            throw new IllegalArgumentException("on_text_mention requires a non-blank text field");
        }
    }
}

Try / catch

try {
    compiler.compile(agentConfig);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("on_text_mention requires text")) {
        // set the text trigger string on the handoff
    }
    throw e;
}

Prevention

When it happens

Trigger: A HandoffConfig with type='on_text_mention' where the text field is null, empty, or whitespace-only (checked via isBlank()).

Common situations: Setting up an on_text_mention handoff but forgetting to specify what text to watch for, or leaving text as an empty string from a variable that wasn't populated.

Related errors

AI-assisted analysis of conductor-oss/conductor@cf7c3e4a8a (2026-08-14). Data as JSON: /api/errors/bdee2d95435517ca. Report an issue: GitHub.