Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
difyPublic
Dify
Documentsdify
LLM Provider Message Validation
LLM Provider Message Validation
Type
Topic
Status
Published
Created
Aug 5, 2026
Updated
Aug 21, 2026
Created by
Dosu Bot
Updated by
Dosu Bot

LLM Provider Message Validation#

Overview#

Different LLM providers impose varying strictness on the structure and content of messages they accept. The Dify agent adapter (dify-agent/src/dify_agent/adapters/llm/model.py) normalizes messages before dispatching to the plugin daemon, applying two categories of validation:

  1. Empty/whitespace filtering β€” blank content is stripped to avoid provider rejections
  2. System message ordering and merging β€” multiple system messages are collapsed into a single leading message to satisfy strict provider templates (e.g., Qwen3.5/3.6 via vLLM)

Why This Matters#

vLLM's Qwen3.5/3.6 chat template enforces that any system message not at position 0 triggers a 400 error β€” including a second consecutive system message after the first . Because neither vLLM's OpenAI-compatible endpoint nor the openai_api_compatible provider plugin merge system messages server-side, the caller (Dify's adapter) must guarantee the invariant: exactly one system message at index 0 .

Key Validation Points#

1. System Prompt Whitespace Filtering#

In _map_messages_to_prompt_messages, runtime instruction parts are filtered via .strip() before being wrapped as SystemPromptMessage:

Line 308: if part.content.strip()

This prevents blank or whitespace-only entries from becoming empty leading system messages sent to the provider.

2. System Message Ordering and Merging#

After filtering, _map_messages_to_prompt_messages calls _order_system_messages_first(prompt_messages, instruction_messages) to merge all system content into a single leading message. The function:

  1. Iterates through all prompt_messages and extracts text content from any SystemPromptMessage instances
  2. Extracts text content from all instruction_messages (runtime instructions from model_request_parameters)
  3. Merges all system content into a single string joined by "\n\n"
  4. Returns a new list with a single SystemPromptMessage containing the merged content as the first element, followed by all non-system messages

Some LLM providers (e.g., Qwen via vLLM) require that the system message be exactly the first element in the messages array and reject multiple system messages. The merging behavior ensures compatibility with these strict provider templates while preserving the relative ordering of user/assistant/tool messages.

The fix was introduced to address vLLM/Qwen compatibility failures documented in and refined in . The two PRs also verify the behavior with regression tests covering:

  • Scattered system messages merged into a single leading message
  • Runtime instructions combined with in-history system messages
  • Whitespace-only system content dropped entirely

3. Tool Description Fallback#

In _map_tool_definitions_to_prompt_tools, tool descriptions use an or "" fallback to avoid sending None to providers that require the field to be a string. No further stripping is applied to tool descriptions in the current implementation.

Message Mapping Architecture#

All validation happens inside _build_request_input , which calls:

HelperResponsibility
_map_messages_to_prompt_messagesConvert + order + filter system prompts
_map_tool_definitions_to_prompt_toolsConvert tool defs, fallback empty description
_map_model_settings_to_parametersMap model settings to provider parameters

The result is passed directly to the plugin daemon's iter_llm_result_chunks transport .

Relevant Files & References#

  • Primary adapter: dify-agent/src/dify_agent/adapters/llm/model.py
  • PR #39136 β€” Initial system message merge fix for Qwen/vLLM
  • PR #39704 β€” Refined fix with explicit whitespace-filtering documentation
Documents
Account Activity Tracking
Agent API Routes
Agent App Architecture
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Agent App Event Architecture
Agent App Input Variables
Agent Cost and Usage Tracking
Agent File Handling
Agent File Upload Configuration
Agent Icon Data Model
Agent Log Event Pipeline
Agent Message History
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Agent Model Settings
Agent Node Data Models
Agent Response Schema
Agent Runtime
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Agent Runtime Backend Initialization
Agent Runtime Layer Provider Registration
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Agent Sandbox SSRF Allowlisting
Agent Shell Layer
Agent Strategy Plugin Architecture
Agent V2 Architecture
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Agent V2 Configure Interface
Agent V2 Feature Flags
Agent V2 File and Vision Handling
Agent V2 Variable System
API Documentation Pipeline
App Mode Configuration
App Publishing and Embedding
Audio to Text API
Auth Route Architecture
Automatic Rule Generation
Avatar Management
Branding Customization
Browser Tab and State Management
Builtin Tool Provider Credentials
Celery Task Resilience
Chat Avatar Rendering
Chatbot Conversation State Recovery
Chatbot Widget Embedding
Code Node Execution
Code Node Output Validation
Collaborative Workflow Editing
Conversation Auto-Naming
Conversation Deep-Linking
Credential Encryption and Secret Management
CSV Data Ingestion
Custom Tool Authentication
Custom Tool HTTP Timeout Configuration
Custom Tool OpenAPI Integration
Data Export
Database Migration System
Database Session Management
Database Transaction Isolation
Dataset Batch Import
Dataset Deletion
Dataset Permission Model
Dataset Segmentation Configuration
Dependency Injection and Testability
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Dify Agent Monorepo Structure
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Dify Cloud Billing
Dify OpenAPI
difyctl CLI
Docker Container Security
Docker Deployment and Upgrades
Docker Frontend Configuration
Docker Image Publishing
Docker Networking
Docker Storage and Permissions
Document Indexing Operations
Edition-Based Feature Gating
Elasticsearch Integration
Embedding Cache Integrity
External Knowledge Integration
File Access Control
File Array Handling
File Download Architecture
File Download Security
File Storage Synchronization
File Upload and Download Integrity
File Upload Configuration
File Upload Processing
File URL Resolution
Flask Application Architecture
Flask Blueprint and Route Registration
Graph Streaming Infrastructure
Home Directory Management
HTTP Request Node
HTTP Request Node Key-Value Editor
HTTP Request Node Size Constraints
httpx and Gevent Compatibility
Human Input Node
Hybrid Search
Icon URL Resolution
Iframe Embedding Security
Internationalization and Locale Management
Jina Reranker Integration
JSON-in-Markdown Parsing
JWT Authentication
Knowledge Base API
Knowledge Base Document Processing
Knowledge Base Metadata Filtering
Knowledge Base Summarization Pipeline
Langfuse Integration
Lexical Editor Integration
LLM Provider Message Validation
LLM Structured Output
Local Development Configuration
Local Embedding Model Deployment
Log Filtering
Markdown Extractor Heading Parsing
Markdown Rendering
MCP Client Transport and Connectivity
MCP Protocol Integration for Dify Workflows
MCP OAuth Integration
MCP Protocol Integration
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
MCP Protocol Integration for Dify Workflows
MCP Provider Architecture
MCP Tool Integration
MCP Protocol Integration for Dify Workflows
MCP Tool Parameter Binding
Messaging Platform Integration
Milvus Integration
Model Provider Error Handling
Monaco Editor Integration
Multi-Tenant Context Propagation
Multimodal Knowledge Base Support
Next.js Routing and Redirects
Next.js SSR Authentication
Nginx Reverse Proxy Configuration
Notion Extractor Table Parsing
NumPy CPU Compatibility
OAuth Login Flow
Observability and Tracing
OpenAI-Compatible Server Integration
OpenAPI Spec Accuracy
OpenDAL Storage Backend
Ops Trace Data Models
Oracle Database Connectivity
Parallel Workflow Execution
Parent-Child Retrieval Architecture
Plugin API Key Configuration
Plugin Architecture
Plugin Credential Management
Plugin Daemon Architecture
Plugin Daemon Communication
Plugin Daemon Model Parameter Handling
Plugin Daemon Port Configuration
Plugin Database Integrity
Plugin Error Handling
Plugin File Handling
Plugin Lifecycle Management
Plugin Marketplace Connectivity
Plugin Model Caching
Plugin Permissions
Plugin Storage Configuration
Plugin System Timeouts
Plugin Taxonomy and Validation
Plugin Trigger OAuth Refresh
Private Address Detection
Provider Model & Credential Management
Pyrefly Type Checker
Rate Limiting and Concurrency Control
RBAC Initialization
Reasoning Model Integration
Reasoning Tag Filtering
Redis Connection Management
Redis Streaming Resilience
Release Breaking Changes
Remote File Handling and Validation
Retrieval Filtering and Scoring
RTL Locale Support
Sandbox Code Execution
Sandbox Network Isolation
Sandbox Seccomp Security
Segment Update and Attachment Lifecycle
Server Deployment Configuration
Service API Error Handling
Service API Pagination
Shell Provider Lifecycle
Snippet Variable Handling
SQLite Test Infrastructure
SSE Stream Lifecycle
SSE Stream Terminal Event Delivery
SSR Data Fetching
SSRF Proxy
Suggested Questions After Answer
Summary Index
Tenant-Isolated Document Indexing Queue
Test Doubles and In-Memory Repositories
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
TiDB Vector Full-Text Search
Time Tools
Timestamp Management
Tool File URL Signing
Tool Node Input Validation
Tool Provider Authorization
Trace Task Pipeline
User and Tenant Context Propagation
User Roles and Permissions
Variable Pool Falsy Value Handling
Variable Resolution and Template Substitution
Vector Database Plugin Architecture
Vector Store Integration
Weaviate Vector Store
Web Container Docker Configuration
Webhook Trigger System
WebSocket Service Architecture
Word Document Extraction
Workflow Agent Node Configuration
Workflow Agent Retry Configuration
Workflow and Agent Composition
Workflow Conditional Branching
Workflow Container Nodes
Workflow Conversation State Management
Workflow Draft Synchronization
Workflow Execution Dispatch
Workflow Execution Persistence
Workflow Fail Branch Architecture
Workflow File Handling
Workflow Iteration Node Execution
Workflow LLM Node Configuration
Workflow Memory Management
Dify Agent Server ζ¨‘ε—εˆ†ζž (Commit 55f95dbc)
Workflow Node Canvas Summary Rendering
Workflow Node Versioning
Workflow Pause-Resume State Management
Workflow Resume Architecture
Workflow Run State Management
Workflow Schedule Triggers
Workflow Test Run Execution
Workflow Timeout and Execution Limits
Workflow Tool Visibility and Access Control
Workflow Variable Size Management