Common Errors

Common build and runtime errors

QQQ 4.0 release. Final 4.0.0 is available. See QQQ 4.0 for release scope and migration guidance.

Build setup

• Java errors: check java -version and mvn -version; both must use Java 21 for this train.
• Missing dependencies: check the selected version and repository availability. RC and final coordinates are different; do not substitute an unpublished version.
• Sample not in reactor: build the root first, then use mvn -f qqq-sample-project/pom.xml clean verify from the root directory.
• Container test failure: inspect Docker availability and the failing module's test report before changing code.
• Coverage or style failure: use the actual selected POM's rules and module-specific baselines. Do not bypass the gate or assume a universal 80%/95% target.

Application setup

Initialize QContext at the appropriate entry point and clear it after a manually initialized scope. In tests, inspect the chosen BaseTest setup instead of assuming every test base installs the same metadata or session.

Validate the assembled QInstance. Confirm backend names, actual database schema, table names, field mappings, and registered process classes. Runtime properties and ports belong to the selected application; there is no universal qqq.database YAML configuration.

Use synthetic data with the sample's explicitly enabled mock authentication. Check the application README for the server entry point and database setup. When a port is busy, identify the owning process and stop it normally or configure the application deliberately.

Diagnose before changing

Read the failing module's target/surefire-reports and the relevant cause chain. Inspect the resolved graph with mvn dependency:tree. Never print API keys, passwords, or full environment files when collecting evidence. Troubleshooting guides cover build, database, authentication, and performance issues.