Skip to main content

​
Installation and setup

Your build tool may require a different Java version than what is currently active. Verify which version is active:
java -version
echo $JAVA_HOME
Check what your project targets (e.g. sourceCompatibility in build.gradle or maven.compiler.source in pom.xml) and ensure a compatible Java version is installed and selected. For example, a project targeting Java 18 needs at least Java 18 — but Java 21 works too.Update JAVA_HOME and PATH to point to the correct installation:
export JAVA_HOME=/path/to/correct/jdk
export PATH="$JAVA_HOME/bin:$PATH"
Diffblue Agents uses the Python interpreter on your PATH. Verify which version is active:
python3 --version
If your project uses a virtual environment, activate it before running the workflow:
source venv/bin/activate
Diffblue Agents requires Python 3.9 or later. If you have multiple Python versions installed, ensure the correct one is first on your PATH.
Diffblue Agents requires a supported AI coding agent platform on your PATH and authenticated. Verify it is available:
claude --version
If the command is not found, install and authenticate the coding agent before running Diffblue Agents. Check the system requirements for supported platforms.
macOS may quarantine files downloaded from the internet. Remove the quarantine attribute:
xattr -r -d com.apple.quarantine diffblue-agents/
Windows may block downloaded scripts. Unblock the required files in PowerShell:
Unblock-File cli\diffblue-agents.ps1
Unblock-File server\diffblue-agents-server.ps1
Unblock-File jre\bin\java.exe
Restart your terminal after unblocking.
Another process is using the assigned port. Either stop the other process, or override the port:
DIFFBLUE_AGENTS_SERVER_PORT=9090 diffblue-agents run regression-unit-tests
The CLI cannot reach the Diffblue Agents Server. Check the port the server is running on from .diffblue/server.json in your project root:
cat .diffblue/server.json
Then verify the server is reachable:
curl http://localhost:<port>/workflows
If .diffblue/server.json does not exist, the server is not running. A stale file (where the PID is no longer active) indicates the server crashed — restart the workflow.

​
Licensing

Check the following:
  • Your machine can reach https://api.licensespring.com and https://licensing.diffblue.com. Check that firewall rules allow outbound connections to these URLs.
  • Your system clock is accurate. License validation is time-sensitive.
  • The license key is entered correctly, including hyphens.
If the issue persists, contact your Diffblue account manager.
Your license quota (measured in additional lines covered) has been reached. The current workflow completes its in-progress work but does not start new partitions.Check your remaining quota:
diffblue-agents license
Contact your Diffblue account manager to discuss increasing your quota.

​
Workflow execution

The workflow checks that your project builds and existing tests pass before generating new tests. If validation fails:
  1. Verify the project builds:
    • Maven: mvn compile
    • Gradle: ./gradlew clean build
  2. Verify existing tests pass:
    • Maven: mvn test
    • Gradle: ./gradlew test
  3. Ensure JaCoCo is configured and Mockito is in your test dependencies.
  4. Fix any build or test failures, then re-run the workflow.
Diffblue Agents validates every generated test by compiling and running it. Tests that fail validation are rolled back automatically. This is expected behavior. The workflow summary shows how many tests were committed and how many were rolled back.A high rollback rate may indicate that the target code is difficult to test in isolation, or that the project has complex dependencies that affect test execution.
Diffblue Agents generates tests in a temporary worktree and cherry-picks committed tests back to your branch. If you made changes to the same files while the workflow was running, cherry-pick conflicts can occur.Resolve conflicts using standard git conflict resolution. The workflow reports which commits had conflicts.

​
Still need help?

If your issue is not listed here, ask on the Diffblue community forum or see the support page for all available channels.