Troubleshooting and Limitations

Table of Contents

Limitations
Troubleshooting
Findings That Need Manual Work
Getting Support

Need help?

Schedule a consultation with an Azul performance expert.

Limitations

Compile-clean is not behavior-preserved: The tool proves the project builds, not that it still behaves the same. Run your own tests.
No deployment: Deployment and runtime verification are not part of this release.
Vendor-proprietary APIs: The tool does not translate another vendor’s APIs. Applications that depend on them can produce a partial result.
Gradle and Ant projects: Source and descriptor findings are handled, but dependency changes are written for Maven pom.xml files only and are partly manual for other build tools.
Server-side settings: Findings that need a real server (domain, cluster, JMS and similar settings) are never applied. They are reported as a Guide for you to run.
Model quality varies: Results, cost and speed depend on the LLM you use. Small self-hosted models may not be capable enough for the complexity of the changes. See Choosing an LLM.
Very large or already partly migrated codebases: In our tests, a large codebase with existing javax/jakarta mismatches across many files was not fully upgraded. The agent deferred a risky bulk refactoring and asked for direction instead of guessing. Run the tool on one module at a time and review results between runs.

Troubleshooting

Problem What to do

Problem	What to do
"Nothing to do", or no stage runs	Pick a stage on the start page. With none picked, advisors and recipes run.
The agent run stops with a timeout	Raise `PAYARA_AI_TIMEOUT`, or use a faster model. Run again: the rest is picked up.
`Compilation: FAILED` after a run	Open the compile section of the report. Some failures come from the project itself, for example a build rule that caps the Java version, and not from the migration.
I want to see the changes before they are made	Turn off applying changes with `-Dmigration.apply=false`.
I want to undo a run	Use git. Each step is a commit named "Migration checkpoint: …".
The migration does not start because of git	The tool commits after each step and needs a clean repository. Commit your changes, or set `migration.gitCommit=false`.
The start page does not open	Use the link printed in the terminal. It contains a random key for this session and only works on your machine.
The agent makes no progress or the round limit is reached	Nothing is rolled back. If the project does not compile, the pipeline checks show a failed Final Compile Check. Check the report for the findings that remain. Run again, because each run starts from the current state of your code, or raise `migration.maxRounds`.
Claude Code cannot see the tools	Run `claude mcp list`. The `java -jar … mcp` command must run on its own without printing an error.
The server was added but `/mcp` does not list it	Start a new Claude Code session. A running session does not pick up a new server. Also check that you ran `claude mcp add` in your project’s folder, or used `--scope user`.
Ollama or custom endpoint connection problems	Check that `PAYARA_AI_PROVIDER_LOCATION` is set to the base URL of the server. Enable `PAYARA_AI_LOG_REQUESTS` and `PAYARA_AI_LOG_RESPONSES` to see what is exchanged.

"Nothing to do", or no stage runs

Pick a stage on the start page. With none picked, advisors and recipes run.

The agent run stops with a timeout

Raise PAYARA_AI_TIMEOUT, or use a faster model. Run again: the rest is picked up.

Compilation: FAILED after a run

Open the compile section of the report. Some failures come from the project itself, for example a build rule that caps the Java version, and not from the migration.

I want to see the changes before they are made

Turn off applying changes with -Dmigration.apply=false.

I want to undo a run

Use git. Each step is a commit named "Migration checkpoint: …".

The migration does not start because of git

The tool commits after each step and needs a clean repository. Commit your changes, or set migration.gitCommit=false.

The start page does not open

Use the link printed in the terminal. It contains a random key for this session and only works on your machine.

The agent makes no progress or the round limit is reached

Nothing is rolled back. If the project does not compile, the pipeline checks show a failed Final Compile Check. Check the report for the findings that remain. Run again, because each run starts from the current state of your code, or raise migration.maxRounds.

Claude Code cannot see the tools

Run claude mcp list. The java -jar … mcp command must run on its own without printing an error.

The server was added but /mcp does not list it

Start a new Claude Code session. A running session does not pick up a new server. Also check that you ran claude mcp add in your project’s folder, or used --scope user.

Ollama or custom endpoint connection problems

Check that PAYARA_AI_PROVIDER_LOCATION is set to the base URL of the server. Enable PAYARA_AI_LOG_REQUESTS and PAYARA_AI_LOG_RESPONSES to see what is exchanged.

Findings That Need Manual Work

Some findings need a decision or an action from you. They do not block the tool from finishing, and are listed in the report.

MANUAL findings can only be done by a person, such as a server setting or an asadmin command. Use post-migration-checklist.md, which has the steps with your project’s values filled in.
AI findings that the agent did not fix are listed in the report with the recommended Fix, so you can apply them yourself.

See Kinds of Findings.

Getting Support

Contact [email protected] for any technical question or problem regarding the Azul Payara AI Upgrade Assistant.