Troubleshooting

spring-cli is not found

The installer places the executable in ~/.local/bin by default. Add that directory to your PATH, then open a new shell:

export PATH="$HOME/.local/bin:$PATH"

On Windows, add the directory containing the downloaded executable to your user PATH.

The installer reports an unsupported platform

The installer supports Linux and macOS on x64 and ARM64. Windows x64 is a manual release download. For unsupported systems or architectures, check the available release assets.

The Linux/macOS installer requires curl and a SHA-256 utility (sha256sum or shasum).

Project creation cannot reach Spring Initializr

Project creation downloads a starter archive from Spring Initializr. Check your network and proxy settings. To use a compatible Initializr service, set SPRING_INITIALIZR_URL to its base URL. The CLI uses https://start.spring.io when this variable is unset.

If metadata lookup fails while choosing versions or dependencies interactively, spring-cli can fall back to its defaults. A failed starter archive download stops creation.

deps list and deps upgrade also need network access to Maven Central. Set SPRING_CLI_MAVEN_CENTRAL_URL if your environment uses a compatible mirror.

A project command cannot find spring-cli.json

Run the command from the project directory or one of its subdirectories. spring-cli searches the current directory and its parents for spring-cli.json. If the file is missing, create a project with spring-cli create or restore the project config.

Maven or Java is unavailable

run and test use the Maven Wrapper from the project root when available; otherwise they require system Maven on PATH. A JDK compatible with the project's javaVersion is also required to compile and run the application.

spring-cli schema apply cannot find or parse the schema

By default, schema apply reads schema.json from the project root. Check project.schemaFile in spring-cli.json if you chose a different filename. The file must be valid JSON containing an entities object and every relationship target must name an entity in that object. See the entity schema reference.

If an entity Java file already exists, generation refuses to replace it unless --force is passed.

dockerize reports that a file already exists

dockerize creates Dockerfile, docker-compose.yml, and .dockerignore. Move or edit the existing file, or use spring-cli dockerize --force to overwrite the generated Docker configuration.

env sync cannot find .env.example

Create .env.example in the project root. env sync compares its variable names with .env; it does not create either file or fill in values.