Check your setup

Use this page before the Quick Start, or when your first project does not run.

Confirm Java and Maven

Install a JDK 17 or later, rather than only a Java runtime, and Apache Maven. In a new terminal, check:

java -version
javac -version
mvn -v

Both Java commands should report version 17 or later. Maven reports the Java version and Java home it uses; check those too. If Maven uses a different JDK, configure JAVA_HOME or your environment’s Java selection, then reopen the terminal. Apache’s installation guide explains PATH and JAVA_HOME configuration.

The first build needs access to Maven repositories to download the archetype, compiler and dependencies. Later builds can reuse downloaded artifacts.

Choose an editor

Create the project using the Quick Start, then open the resulting folder. ASTRA sources remain plain text files, and Maven supplies the compilation and launch workflow.

Visual Studio Code: install the ASTRA syntax-highlighting extension by searching for astra in Extensions. Its Java build-tools guide explains Maven integration for the Java parts of your project.
IntelliJ IDEA: open the generated pom.xml as a project, following JetBrains’ Maven guide. The community ASTRA TextMate grammar provides syntax highlighting.
Neovim: see the community ASTRA tree-sitter grammar.

Syntax highlighting helps you read code; use Maven’s compiler messages to check the program. Configure your IDE to use a suitable JDK as well as the terminal.

Know which files to edit

Location	Purpose
`pom.xml`	Dependencies, ASTRA version and build configuration
`src/main/astra/Main.astra`	The first agent program
`src/main/java/`	Java modules and supporting classes, when your application needs them
`target/`	Generated sources, compiled classes and other build output

Edit files under src, rather than generated copies under target. Run Maven from the project folder containing pom.xml. Keep each agent’s class name and filename aligned; packages are explained in Building and deploying.

If the first run fails

Symptom	Check
`java`, `javac` or `mvn` is not found	Install the missing tool and check `PATH` in a new terminal.
Java version or class-version error	Check the JDK reported by `mvn -v`, not only `java -version`.
Maven cannot find a project	Change into the generated project folder containing `pom.xml`.
Archetype or dependency cannot be downloaded	Read the repository error; check connectivity and your organization’s Maven proxy/settings.
ASTRA reports a source error	Fix the reported file and line, save and compile again.
Your edit is not reflected in the output	Stop the old process, save the source and run Maven again.
The greeting prints but the terminal stays busy	ASTRA remains running; press `Ctrl+C` to stop this example.

For a reproducible problem report, include the command, the relevant compiler/runtime error, your ASTRA version from pom.xml, and the Java/Maven versions. Remove credentials from logs before sharing them.

Continue

Follow the Quick Start to create, run and change an agent. Then start Understanding an agent. Use Building and deploying when you need to choose another main class or change the build, and Testing, building and running when developing a larger application.