{"record":{"id":"bdee2d95435517ca","repo":"conductor-oss/conductor","slug":"on-text-mention-requires-text","errorCode":null,"errorMessage":"on_text_mention requires text","messagePattern":"on_text_mention requires text","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":400,"severity":"error","filePath":"agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/MultiAgentCompiler.java","lineNumber":1505,"sourceCode":"                    || !Set.of(\"on_tool_result\", \"on_text_mention\", \"on_condition\")\n                            .contains(handoff.getType())) {\n                throw new IllegalArgumentException(\n                        \"SWARM handoff type must be on_tool_result, on_text_mention, or on_condition\");\n            }\n            if (handoff.getTarget() == null || !targets.contains(handoff.getTarget())) {\n                throw new IllegalArgumentException(\n                        \"SWARM handoff target must name a swarm agent: \" + handoff.getTarget());\n            }\n            switch (handoff.getType()) {\n                case \"on_tool_result\" -> {\n                    if (isBlank(handoff.getToolName()) || isBlank(handoff.getResultContains())) {\n                        throw new IllegalArgumentException(\n                                \"on_tool_result requires toolName and resultContains\");\n                    }\n                }\n                case \"on_text_mention\" -> {\n                    if (isBlank(handoff.getText())) {\n                        throw new IllegalArgumentException(\"on_text_mention requires text\");\n                    }\n                }\n                case \"on_condition\" -> {\n                    if (isBlank(handoff.getTaskName())) {\n                        throw new IllegalArgumentException(\n                                \"on_condition requires a nonblank taskName\");\n                    }\n                }\n                default -> throw new IllegalStateException(\"validated above\");\n            }\n        }\n    }\n\n    private static boolean isBlank(String value) {\n        return value == null || value.isBlank();\n    }\n\n    /**","sourceCodeStart":1487,"sourceCodeEnd":1523,"githubUrl":"https://github.com/conductor-oss/conductor/blob/cf7c3e4a8adfb158be778ab1ec525323c363cd3a/agentspan/src/main/java/org/conductoross/conductor/ai/agentspan/runtime/compiler/MultiAgentCompiler.java#L1487-L1523","documentation":"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.","triggerScenarios":"A HandoffConfig with type='on_text_mention' where the text field is null, empty, or whitespace-only (checked via isBlank()).","commonSituations":"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.","solutions":["Set the handoff's text field to a non-blank string that should trigger the handoff when it appears in conversation.","Choose a text value that won't produce false positives in normal conversation."],"exampleFix":"// before\n{\"type\": \"on_text_mention\", \"target\": \"billing_agent\", \"text\": \"\"}\n// after\n{\"type\": \"on_text_mention\", \"target\": \"billing_agent\", \"text\": \"I need a refund\"}","handlingStrategy":"validation","validationCode":"void validateOnTextMention(HandoffConfig h) {\n    if (\"on_text_mention\".equals(h.getType())) {\n        if (h.getText() == null || h.getText().isBlank()) {\n            throw new IllegalArgumentException(\"on_text_mention requires a non-blank text field\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    compiler.compile(agentConfig);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"on_text_mention requires text\")) {\n        // set the text trigger string on the handoff\n    }\n    throw e;\n}","preventionTips":["Always specify the exact text phrase that should trigger the handoff.","Test that the chosen trigger text is specific enough to avoid unintended handoffs."],"tags":["swarm","handoff","on-text-mention","config-validation","agentspan"],"backgroundTag":null,"analyzedSha":"cf7c3e4a8adfb158be778ab1ec525323c363cd3a","analyzedAt":"2026-08-14T03:33:19.897Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}