Twilio error 12100 means Twilio received a response from your webhook but failed to parse it as valid XML, which is the foundation that all TwiML documents must satisfy before Twilio can interpret any verbs or attributes. TwiML is XML, and XML is strict: a single unclosed tag, an unescaped ampersand in text content, or a stray byte before the XML declaration will cause the entire document to fail parsing. Because Twilio cannot fall back to partial TwiML parsing, a 12100 error means the entire call or message instruction set is lost.
What Causes This Error
The single most common cause in PHP applications is output buffering being disabled, causing any whitespace or output before the opening XML declaration to be sent as part of the response body, which corrupts the XML structure since the XML declaration must be the very first bytes of the document. Unescaped special characters in TwiML text content are a second major cause: if a Say verb's body contains an ampersand (&), a less-than sign (<), or a greater-than sign (>) that was not properly escaped as XML entities (&, <, >), the XML parser fails to parse the document. Truncated responses are a third cause: if your server sends an HTTP response with a Content-Length header that is larger than the actual body it sends (or closes the connection before the body is complete), Twilio receives an incomplete XML document that fails parsing. Using non-UTF-8 character encodings in your TwiML without declaring the correct encoding in the XML declaration can also cause 12100 when your response body contains characters that are valid in ISO-8859-1 or Windows-1252 but invalid in UTF-8.
How to Fix It Step by Step
Retrieve the exact TwiML your webhook is returning by using curl -s https://your-webhook-url and piping the output to an XML validator such as xmllint --noout (xmllint --noout -), which will report the precise line and character position of any XML parse error. Check that the very first bytes of your response body are the XML declaration <?xml version="1.0" encoding="UTF-8"?> or the TwiML root element <Response>, with no preceding whitespace, BOM characters, HTML error output, debug print statements, or blank lines. Escape all dynamic content that is interpolated into TwiML text nodes using your language's XML escaping function: htmlspecialchars() in PHP, xml.sax.saxutils.escape() in Python, or Twilio's official TwiML builder library which handles escaping automatically. After making corrections, paste your TwiML into Twilio's TwiML Validator (available in the Twilio Console under Tools) or use an online XML validator to confirm the document is well-formed XML before deploying.
How to Prevent It from Recurring
Use the official Twilio helper library for your language (twilio-node, twilio-python, twilio-ruby, or twilio-java) to generate TwiML programmatically rather than building XML strings by hand: the library's TwiML builder classes handle tag nesting, attribute formatting, and character escaping automatically, making malformed TwiML structurally impossible from the builder layer. Add an automated test in your CI pipeline that calls your webhook handler with a simulated Twilio request payload and validates the response body using an XML parser, so malformed TwiML is caught before deployment. Enable strict output buffering in PHP by setting output_buffering = On in your php.ini and adding ob_start() at the top of every TwiML-generating script, ensuring no premature output reaches the response body before your headers and XML declaration. For dynamic TwiML that interpolates user data or database values, add a schema validation step using an XML Schema Definition (XSD) for TwiML to catch not only XML well-formedness errors but also TwiML-specific structural violations.
When to Call a Specialist
If your TwiML validates successfully in xmllint and in Twilio's TwiML Validator but Twilio still returns 12100 in production, the TwiML your test tools receive may differ from what Twilio receives due to a difference in request headers: Twilio's POST request includes an Accept header of text/xml that some servers use to return different response formats, and if your server returns something other than XML for that Accept value, Twilio gets a non-XML response while your test tools get a valid one. A specialist can configure a proxy to make requests with the exact headers Twilio uses (including User-Agent, Accept, and the signed X-Twilio-Signature header) and inspect the response your server returns for those specific headers. You should also seek specialist help if 12100 errors are intermittent and only occur on specific calls, as this pattern often indicates a race condition or an error path in your code that returns an HTML error page instead of TwiML when a specific condition (database timeout, null pointer, unhandled exception) is triggered. Intermittent TwiML parse failures during active call flows are high-severity issues that require fast diagnosis.
Conclusion
Error 12100 is a TwiML XML parse failure that is fixed by ensuring your webhook returns a well-formed XML document with no preceding output, properly escaped content, and no truncation. If this error is blocking your production system, contact our team and we will diagnose and fix it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.