Troubleshooting Smart Connector Generation Failures from RAML in Exchange

Smart connector generation can fail due to various issues within the RAML or OAS specification that prevent the generator from correctly parsing or processing the API definition.

Before publishing your API specification to Exchange, verify the following points in your RAML or OAS definition:

1. URL-Reserved Characters in Values:
   Ensure there are no colons (:) or spaces (), or other URL-reserved characters, in values that become part of a URL or identifier. This includes baseUri and id/example values. The generator passes these directly into a URI parser, which can throw errors like "Illegal character in scheme name at index 0…".
   Example: An id value like 2026-03-18T10:14:55Z contains colons and will cause a failure.

2. Absolute baseUri / servers.url:
   The baseUri (for RAML) or servers.url (for OAS) must be present and an absolute URL (e.g., https://api.example.com/v1), not a relative path.

3. {version} Placeholder with Defined Version:
   If your baseUri uses a {version} placeholder, the API specification must explicitly define a version.

4. No Duplicate Parameter Names:
   Ensure there are no duplicate parameter names within a single operation. This applies after combining URI, query, header, and form parameters. Duplicate parameter names can lead to schema validation failures during connector generation.

5. Supported Authentication Types:
   Only the following authentication types are supported: Basic, OAuth 2.0, Pass-through, Digest, Custom, JWT, or unsecured. OAuth 1.0 is not supported for smart connector generation.

6. Supported Specification Formats:
   The supported API specification formats are RAML 0.8/1.0 and OAS 2.0. OAS 3.x has limited support.

7. Valid Body Media Types and Type/Schema Definitions:
   Verify that all body media types and their corresponding type/schema property definitions are valid and supported by the connector generator.
   
   

By checking these common issues, you can identify and resolve problems that lead to smart connector generation failures and non-descriptive error emails.

If these validations still doesnt resolve the issue at your end, please raise a support ticket with Mulesoft to check further.