> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diffblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common issues with Diffblue Agents

## Installation and setup

<AccordionGroup>
  <Accordion title="Java version mismatch when building a project">
    Your build tool may require a different Java version than what is currently active. Verify which version is active:

    ```bash theme={null}
    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:

    ```bash theme={null}
    export JAVA_HOME=/path/to/correct/jdk
    export PATH="$JAVA_HOME/bin:$PATH"
    ```
  </Accordion>

  <Accordion title="Python version not detected or wrong version used">
    Diffblue Agents uses the Python interpreter on your `PATH`. Verify which version is active:

    ```bash theme={null}
    python3 --version
    ```

    If your project uses a virtual environment, activate it before running the workflow:

    ```bash theme={null}
    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`.
  </Accordion>

  <Accordion title="Coding agent not detected">
    Diffblue Agents requires a [supported AI coding agent platform](/system-requirements#supported-ai-coding-agent-platforms) on your `PATH` and authenticated. Verify it is available:

    ```bash theme={null}
    claude --version
    ```

    If the command is not found, install and authenticate the coding agent before running Diffblue Agents. Check the [system requirements](/system-requirements) for supported platforms.
  </Accordion>

  <Accordion title="macOS: quarantine warning on first run">
    macOS may quarantine files downloaded from the internet. Remove the quarantine attribute:

    ```bash theme={null}
    xattr -r -d com.apple.quarantine diffblue-agents/
    ```
  </Accordion>

  <Accordion title="Windows: scripts blocked from executing">
    Windows may block downloaded scripts from executing. In PowerShell, navigate into the Diffblue Agents installation directory and run:

    ```powershell theme={null}
    Unblock-File cli\diffblue-agents.ps1
    Unblock-File server\diffblue-agents-server.ps1
    Unblock-File jre\bin\java.exe
    ```

    Restart your terminal after unblocking.

    If the scripts still fail to execute after unblocking, set your PowerShell execution policy to RemoteSigned for the current user. This allows signed scripts downloaded from the Internet to run:

    ```powershell theme={null}
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    ```
  </Accordion>

  <Accordion title="Server fails to start due to port conflict">
    Another process is using the assigned port. Either stop the other process, or override the port:

    ```bash theme={null}
    DIFFBLUE_AGENTS_SERVER_PORT=9090 diffblue-agents run regression-unit-tests
    ```
  </Accordion>

  <Accordion title="&#x22;fetch failed&#x22; when using the CLI">
    The CLI cannot reach the Diffblue Agents Server. Check the port the server is running on from `.diffblue/server.json` in your project root:

    ```bash theme={null}
    cat .diffblue/server.json
    ```

    Then verify the server is reachable:

    ```bash theme={null}
    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.
  </Accordion>
</AccordionGroup>

## Licensing

<AccordionGroup>
  <Accordion title="License activation fails">
    Check the following:

    * Your machine can reach `https://api.licensespring.com`, `https://licensing.diffblue.com`, and `https://otlp-gateway-prod-gb-south-1.grafana.net`. 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.
    * Your [proxy settings](/reference/network-configuration#proxy-configuration) are correct, if your network requires a proxy.

    If the issue persists, contact your Diffblue account manager.
  </Accordion>

  <Accordion title="&#x22;Agent Not Licensed&#x22; when running a workflow">
    The workflow requires access to an agent that is not enabled on your license. Your license is active but does not include the agent this workflow needs.

    Check which agents are enabled on your license:

    ```bash theme={null}
    diffblue-agents license
    ```

    Look for the **Agents** row in the output. Run `diffblue-agents workflows` to see which workflows you can access and which require additional agent access.

    Visit the [Diffblue pricing page](https://www.diffblue.com/pricing/) or contact your Diffblue account manager to upgrade your license.
  </Accordion>

  <Accordion title="&#x22;quota exceeded&#x22; during workflow execution">
    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:

    ```bash theme={null}
    diffblue-agents license
    ```

    Visit the [Diffblue pricing page](https://www.diffblue.com/pricing/) or contact your Diffblue account manager to upgrade your license.
  </Accordion>
</AccordionGroup>

## Workflow execution

<AccordionGroup>
  <Accordion title="Workflow fails during initial validation">
    The workflow checks that your project builds and existing tests pass before generating new tests. If validation fails:

    <Tip>
      To catch validation issues before running the full workflow, run the [prepare project workflow](/workflows/regression-unit-tests-prepare-project) first.
    </Tip>

    <Tabs>
      <Tab title="Java">
        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.
      </Tab>

      <Tab title="Python">
        1. Verify existing tests pass:
           ```bash theme={null}
           pytest
           ```
        2. Ensure pytest-cov is installed:
           ```bash theme={null}
           pip show pytest-cov
           ```
        3. If your project uses a virtual environment, ensure it is activated.
        4. Fix any test failures, then re-run the workflow.
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Tests are rolled back after generation">
    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.
  </Accordion>

  <Accordion title="Cherry-pick conflicts reported">
    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.
  </Accordion>

  <Accordion title="Environment setup reruns despite no project changes">
    Diffblue Agents caches the build environment state in `.diffblue/project-state.json` to skip environment setup on repeat runs. If the cache is stale or corrupt, delete it to force a fresh setup:

    ```bash theme={null}
    rm .diffblue/project-state.json
    ```

    This file is safe to delete at any time. Diffblue Agents recreates it after the next successful environment setup.
  </Accordion>
</AccordionGroup>

## Still need help?

If your issue is not listed here, ask on the [Diffblue community forum](https://forum.diffblue.com/) or see the [support](/support) page for all available channels.