SOAPless
Sign Up
Back to Blog
javajax-wstroubleshootingweb-services

JAX-WS wsimport Errors: Fixing Code Generation Failures for Complex WSDL Files

SOAPless Team6 min read

wsimport is the standard JAX-WS tool for generating Java client code from WSDL files. It works well for simple services, but the moment you encounter a real-world enterprise WSDL with complex types, multiple schemas, or non-standard patterns, wsimport starts throwing cryptic errors. This guide covers the most common failures and how to fix each one.

Error 1: "Two Declarations Cause a Collision"

This is arguably the most frequent wsimport error with complex WSDLs. It occurs when JAXB (the XML-to-Java binding layer inside wsimport) tries to generate two Java classes or properties with the same name.

[ERROR] Two declarations cause a collision in the ObjectFactory class.
  line 42 of file:/path/to/service.wsdl
[ERROR] (Related to above error) This is the other declaration.
  line 87 of file:/path/to/service.wsdl

Why It Happens

JAXB maps XML element names to Java class names using a set of naming rules. When two XSD types — for example, getUser (an element) and GetUser (a complexType) — map to the same Java class GetUser, the collision occurs.

Fix: JAXB Binding Customization File

Create a jaxb-binding.xml file to resolve the naming conflict:

<?xml version="1.0" encoding="UTF-8"?>
<jaxb:bindings xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
               version="3.0">

  <!-- Rename the conflicting type -->
  <jaxb:bindings schemaLocation="service.wsdl#types?schema1">
    <jaxb:bindings node="//xs:complexType[@name='GetUser']">
      <jaxb:class name="GetUserType"/>
    </jaxb:bindings>
  </jaxb:bindings>

  <!-- Or apply a global suffix rule -->
  <jaxb:bindings>
    <jaxb:nameXmlTransform>
      <jaxb:typeName suffix="Type"/>
    </jaxb:nameXmlTransform>
  </jaxb:bindings>

</jaxb:bindings>

Pass it to wsimport:

wsimport -keep -b jaxb-binding.xml -d output/ service.wsdl

For cases where many collisions exist, a global approach is more practical:

<jaxb:bindings xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb" version="3.0">
  <jaxb:globalBindings>
    <jaxb:serializable uid="1"/>
    <jaxb:javaType name="java.util.Calendar"
                    xmlType="xs:dateTime"
                    parseMethod="jakarta.xml.bind.DatatypeConverter.parseDateTime"
                    printMethod="jakarta.xml.bind.DatatypeConverter.printDateTime"/>
  </jaxb:globalBindings>
</jaxb:bindings>

Error 2: "Undefined Element Declaration"

[ERROR] undefined element declaration 's:schema'
  line 15 of https://api.example.com/service.asmx?wsdl

This error is extremely common with .NET (ASMX and WCF) web services. These services sometimes include Microsoft-specific schema extensions or reference schemas using non-standard prefixes.

Fix: Download and Patch the WSDL

# Download the WSDL locally
curl -o service.wsdl "https://api.example.com/service.asmx?wsdl"

Then fix the problematic element. The s:schema issue usually requires adding the missing schema import:

<!-- Add this inside the <wsdl:types> section -->
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://www.w3.org/2001/XMLSchema"/>
</xs:schema>

Alternatively, use the -extension flag which enables vendor extensions:

wsimport -keep -extension -d output/ service.wsdl

Error 3: "Unsupported Encoding" or Character Issues

[ERROR] unsupported encoding: windows-1252

Some legacy WSDL files declare non-UTF-8 encodings. Modern tools may not support them.

Fix: Convert the Encoding

# Download and re-encode to UTF-8
curl -o service-original.wsdl "https://api.example.com/service?wsdl"
iconv -f WINDOWS-1252 -t UTF-8 service-original.wsdl > service.wsdl

# Update the XML declaration
# Change: <?xml version="1.0" encoding="windows-1252"?>
# To:     <?xml version="1.0" encoding="UTF-8"?>

Error 4: Package Name Collisions

When a WSDL imports multiple schemas with different namespaces, wsimport maps each namespace to a Java package. If two namespaces generate the same package name, compilation fails.

[ERROR] Two classes have the same name
  "com.example.generated.ObjectFactory"

Fix: Explicit Package Mapping

wsimport -keep \
  -p com.example.orders \
  -b package-binding.xml \
  -d output/ \
  service.wsdl

With a binding file for per-schema control:

<?xml version="1.0" encoding="UTF-8"?>
<jaxb:bindings xmlns:jaxb="https://jakarta.ee/xml/ns/jaxb"
               xmlns:xs="http://www.w3.org/2001/XMLSchema"
               version="3.0">

  <jaxb:bindings schemaLocation="service.wsdl#types?schema1">
    <jaxb:schemaBindings>
      <jaxb:package name="com.example.orders.types"/>
    </jaxb:schemaBindings>
  </jaxb:bindings>

  <jaxb:bindings schemaLocation="service.wsdl#types?schema2">
    <jaxb:schemaBindings>
      <jaxb:package name="com.example.orders.common"/>
    </jaxb:schemaBindings>
  </jaxb:bindings>

</jaxb:bindings>

Error 5: Java 11+ Module System Issues

Starting with Java 11, JAX-WS was removed from the JDK. If you see errors like:

error: package javax.xml.ws does not exist
error: package javax.jws does not exist

Fix: Add Jakarta XML Web Services Dependencies

For Java 11+, you need external dependencies. With Maven:

<dependencies>
  <!-- JAX-WS Runtime -->
  <dependency>
    <groupId>jakarta.xml.ws</groupId>
    <artifactId>jakarta.xml.ws-api</artifactId>
    <version>4.0.2</version>
  </dependency>
  <dependency>
    <groupId>com.sun.xml.ws</groupId>
    <artifactId>jaxws-rt</artifactId>
    <version>4.0.3</version>
    <scope>runtime</scope>
  </dependency>

  <!-- JAXB (also removed from JDK) -->
  <dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.2</version>
  </dependency>
  <dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
    <version>4.0.5</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

And use the standalone wsimport from the Jakarta distribution, not the JDK:

# Install via Maven plugin instead of JDK tool
# pom.xml
<plugin>
  <groupId>com.sun.xml.ws</groupId>
  <artifactId>jaxws-maven-plugin</artifactId>
  <version>4.0.3</version>
  <executions>
    <execution>
      <goals><goal>wsimport</goal></goals>
      <configuration>
        <wsdlUrls>
          <wsdlUrl>https://api.example.com/service?wsdl</wsdlUrl>
        </wsdlUrls>
        <packageName>com.example.service</packageName>
        <keep>true</keep>
        <extension>true</extension>
        <bindingFiles>
          <bindingFile>${basedir}/src/main/resources/jaxb-binding.xml</bindingFile>
        </bindingFiles>
      </configuration>
    </execution>
  </executions>
</plugin>

For Gradle:

plugins {
    id 'java'
}

configurations {
    jaxws
}

dependencies {
    jaxws 'com.sun.xml.ws:jaxws-tools:4.0.3'
    implementation 'jakarta.xml.ws:jakarta.xml.ws-api:4.0.2'
    runtimeOnly 'com.sun.xml.ws:jaxws-rt:4.0.3'
}

tasks.register('wsimport', JavaExec) {
    classpath = configurations.jaxws
    mainClass = 'com.sun.tools.ws.WsImport'
    args '-keep',
         '-extension',
         '-d', "${buildDir}/generated-sources/jaxws",
         '-p', 'com.example.service',
         "${projectDir}/src/main/resources/wsdl/service.wsdl"
}

compileJava.dependsOn wsimport
sourceSets.main.java.srcDir "${buildDir}/generated-sources/jaxws"

Error 6: wsdlLocation Runtime Path Issues

Generated code includes a @WebServiceClient annotation with a hardcoded path:

@WebServiceClient(name = "OrderService",
    wsdlLocation = "file:/Users/dev/project/service.wsdl")
public class OrderService extends Service {

This path won't work on other machines or in production.

Fix: Override wsdlLocation

wsimport -keep \
  -wsdllocation /wsdl/OrderService.wsdl \
  -d output/ \
  service.wsdl

Place the WSDL in your classpath (src/main/resources/wsdl/) and load it at runtime:

URL wsdlUrl = OrderService.class.getResource("/wsdl/OrderService.wsdl");
OrderService service = new OrderService(wsdlUrl);
OrderServicePortType port = service.getOrderServicePort();

Complete Troubleshooting Checklist

SymptomLikely CauseFix
Two declarations cause collisionElement/type name overlapJAXB binding file with rename
undefined element s:schema.NET WSDL quirks-extension flag or WSDL patch
Unsupported encodingLegacy WSDL encodingiconv to UTF-8
Same class name in ObjectFactoryNamespace-to-package collisionExplicit package binding
package javax.xml.ws does not existJava 11+ removed JAX-WSAdd Jakarta dependencies
WSDL not found at runtimeHardcoded wsdlLocation-wsdllocation flag
Connection timeout during generationRemote WSDL unreachableDownload locally + catalog

How SOAPless Helps

Every error in this guide exists because of the same root problem: generating and maintaining Java client code from WSDL files is inherently fragile. Schema changes break generated code, name collisions require manual binding files, and Java version upgrades require dependency migrations.

SOAPless takes a different approach. Instead of generating client code, you register your WSDL URL in the SOAPless dashboard, and it creates REST JSON endpoints automatically. Your application sends standard JSON over HTTP — no generated stubs, no JAXB bindings, no wsimport at all. SOAPless handles the JSON-to-SOAP XML conversion, namespace management, and schema resolution on the server side.

SOAP credentials are secured with AES-256-GCM encryption, and every registered service gets auto-generated OpenAPI 3.0 documentation. You can test operations directly from the dashboard before writing any integration code.

Back to Blog