Troubleshooting
This section describes some issues you may encounter and explains how to resolve them.
Changes to resource or method names are not saved
Common cause: Several resources use the same path with different PATH parameters, and you try to switch between them. ReadyAPI uses path values to determine the resource, and cannot see the difference between them.
Suggested solution: Use the provided resource name. The requests will run as expected.
Error when generating a printable report
Common cause: The name of the project, test suite, test case, or load test for which you are trying to create a report contains special symbols, including but not limited to &, -, /, (, or ).
Suggested solution: Remove all the special symbols from the name.
Hanging in macOS
Common cause: Some macOS users experience problems with ReadyAPI hanging and becoming unresponsive.
Suggested solution: Some users who experienced hanging on macOS have resolved their issues by disabling the internal browser.
Note
This will disable the internal browser in general, which means that the Discovery with internal browser feature will not work. You can still do discovery through proxy and use an external browser, though.
Add the following line to the
Applications/<Ready-API-Version>.app/Contents/vmoptions.txtfile:-Dsoapui.browser.disabled=true
Restart ReadyAPI.
Hanging when opening SOAP project with remote service definition
Common cause: Java 7 or later does not trust the website that does not have a signed certificate, so ReadyAPI cannot retrieve the definition.
Suggested solution: Add the website that holds your service definition to the Java Exceptions List. This list is stored in the (<System>\Sun\Java\Deployment\Security\exception.sites) file. Java does not check certificates for files on this list. For detailed instructions on modifying the exceptions list, see the Java documentation.
Hanging when running large functional tests
Common cause: ReadyAPI may stop responding when running a large number of test suites and test cases in parallel.
Suggested solution: Each test step you run in parallel consumes threads available to ReadyAPI. Once it runs out of threads, ReadyAPI can no longer respond to your actions or continue the test run.
Modify your test to use fewer test cases and test suites, or run some test cases or test suites in sequence.
Hanging when validating Groovy syntax
Common cause: ReadyAPI may stop responding when working with Groovy code.
Suggested solution: ReadyAPI uses the Jshint command-line process to automatically validate the Groovy syntax. This may cause ReadyAPI to hang.
A possible workaround is to disable syntax checking. To do this:
Add the following line to the vmoptions file:
-Dgroovy.disable.syntax.checking=false
Restart ReadyAPI.
ReadyAPI displays the splash screen but does not start
Common causes:
There is not enough RAM to start the Java virtual machine.
The Java virtual machine tried to use Java options that cannot be used to run ReadyAPI.
Suggested solutions:
Make sure you run ReadyAPI on a computer that meets the minimum system requirements.
Remove the
JAVA_TOOL_OPTIONSand_JAVA_OPTIONSOS environment variables.
ReadyAPI does not start for users without admin permissions
Common cause: Anti-malware software does not allow JxBrowser to write information to the AppData folder.
Suggested solution: Configure JxBrowser to write information to another folder that is accessible without admin permissions. To do that, add the following line to the vmoptions file: -Djxbrowser.chromium.dir=<NEW_PATH>, where <NEW_PATH> is the path to the folder that JxBrowser should write information to.
Unable to save a project due to a lack of Java heap space
Common cause: You imported a large OpenAPI\Swagger definition.
Suggested solution: Disable the creation of request samples. To do this, add the following JVM options:
-Dsoapui.swagger.resolvefully=false -Dsoapui.swagger.addRequestContent=false
To learn how to do it, see Modifying JVM Settings.
XML parsing errors caused by long URLs
Common cause: ReadyAPI uses Java’s XML parser, which enforces secure processing limits through FEATURE_SECURE_PROCESSING. One of these limits restricts entity or name lengths to a maximum of 1,000 characters (maxXMLNameLimit). Embedding a URL or entity value longer than this limit triggers errors like:
JAXP00010005: The length ... exceeds the “1,000” limit set by FEATURE_SECURE_PROCESSING
To avoid this:
Do not embed large JSON payloads in URLs.
Move payloads into the message body by using POST or PUT methods.
Only increase parsing limits through JVM system properties (for example,
-Djdk.xml.maxXMLNameLimit) or ajaxp.propertiesfile when all XML inputs are fully trusted and controlled.
The Java API for XML Processing (JAXP) Security Guide explains these limits in detail and describes how to configure them.
Background: ReadyAPI relies on Java’s standard XML processing (JAXP), which enforces limits under FEATURE_SECURE_PROCESSING, including:
maxXMLNameLimit(default: 1,000 characters)maxGeneralEntitySizeLimit,totalEntitySizeLimit, and others
Parsing errors occur when embedding very long strings, often JSON objects, in URLs or entities that exceed these limits.
Recommended actions:
Refactor API design to avoid large payloads in URLs. Use HTTP POST or PUT with JSON in the request body instead of path or query parameters.
If adjusting limits is necessary, modify JVM JAXP system properties, for example:
-Djdk.xml.maxXMLNameLimit=5000or addjdk.xml.maxXMLNameLimit=5000tojava.home/lib/jaxp.properties.Warning
Overriding these limits disables built-in security protections. Only do this if all XML inputs come from fully trusted sources.
Supporting links:
The first execution of a test case after starting ReadyAPI is slower than subsequent runs
Common cause: the first request may have some delay caused by the Apache HttpClient library used by ReadyAPI. This is a known limitation.
Unable to log into ReadyAPI with PKCE
If you are having trouble logging in to ReadyAPI with PKCE and other applications, we recommend using the -DinternalBrowserLoginFlow=true flag. See Modifying JVM Settings to learn more about VM options.