If the server fails to launch, exits immediately, or doesn't respond to MCP requests, follow these troubleshooting steps.

1. Check the Java version by running this command in your CLI:

java -version

Ensure Java 17 or higher is installed.

2. Verify the JAR file in the CLI:

ls -la liquibase-mcp-changelog-server-0.1.0.jar java -jar liquibase-mcp-changelog-server-0.1.0.jar --help

- Check that the JAR file exists and is not corrupted.

- Verify the file permissions allow execution.

3. Test the manual startup by running this command in the CLI:

java -jar liquibase-mcp-changelog-server-0.1.0.jar

Look for any startup messages or error output.

If Claude Desktop shows server connection errors, MCP tools aren't available, or the server appears to start but Claude can't connect, follow these troubleshooting steps.

1. Verify your configuration path:

   • Ensure the JAR path in the MCP settings is absolute and correct.

   • Use full paths like:

     /home/user/liquibase-mcp-changelog-server-0.1.0.jar

   • Avoid relative paths or ~/ shortcuts.

2. Check the Claude Desktop logs:

   • On macOS:

     ~/Library/Logs/Claude/

   • On Windows:

     %APPDATA%/Claude/logs/

   • Look for connection errors or startup failures.

3. Test the server manually: Run this command: java -jar liquibase-mcp-changelog-server-0.1.0.jar

   Verify the server starts without errors before configuring Claude Desktop.

4. Ensure your Claude Desktop configuration follows the correct JSON format:

When you see malformed XML, Liquibase validation failures, or XML parsing errors, try these solutions.

1. Check the server logs: The server uses Liquibase's native XML serializer, so output should always be valid. Learn how to capture the server logs in step 6 below.

2. Capture the error output by running this in your CLI:

   java -jar liquibase-mcp-changelog-server-0.1.0.jar 2> error.log

3. Validate your input parameters:

   • Ensure all required parameters are provided

   • Check for special characters in table/column names

   • Verify data types are valid

If you're experiencing slow response times, the server appears to hang, or you encounter timeout errors, follow these troubleshooting steps.

1. Disable validation for development to produce faster responses by running this in the CLI: LIQUIBASE_MCP_DISABLE_VALIDATION=true java -jar liquibase-mcp-changelog-server-0.1.0.jar

2. Check your system resources:

   • Verify sufficient memory is available

   • Monitor CPU usage during operations

3. Optimize your environment variables:

If the Docker container won't start, you encounter permission errors, or the container exits immediately, follow these troubleshooting steps.

1. Verify Docker is installed by running this in the CLI:

   docker --version docker run hello-world

2. Ensure your Docker image is available by running this in the CLI:

   For local builds: docker images | grep liquibase-mcp-changelog-server For remote images: docker pull docker.liquibase.net/liquibase-mcp-changelog-server:0.1.0-SNAPSHOT This command lists all Docker images stored locally or in your server so you can find out what version you're running.

3. Test that you are running in Interactive Mode by running this in the CLI:

   docker run -it liquibase-mcp-changelog-server:local This command allows you to run the Docker container and keep your connection to the server in real time, which will validate if you're connected successfully or not.

4. Debug with Shell Access

   docker run -it --entrypoint /bin/bash liquibase-mcp-changelog-server:local This command allows you to open the CLI inside the running Docker container so you can troubleshoot from within.