Common Errors

Common Errors

Common errors and issues encountered during QQQ development, along with their solutions and prevention strategies.

Quick Links

• Home
• Building Locally
• Testing
• FAQ

Build Errors

Java Version Issues

Error: Unsupported class file major version X Cause: Using Java version older than 17 Solution:

# Check Java version
java -version

# Must show Java 17 or higher
# If not, install Java 17+ and set JAVA_HOME
export JAVA_HOME=/path/to/java17
export PATH=$JAVA_HOME/bin:$PATH

Prevention: Always verify Java version before building

Maven Version Issues

Error: Plugin execution not covered by lifecycle configuration Cause: Maven version too old (QQQ requires 3.8+) Solution:

# Check Maven version
mvn -version

# Must show Maven 3.8 or higher
# If not, update Maven
brew install maven  # macOS
# or download from maven.apache.org

Prevention: Use Maven 3.8+ for QQQ development

Coverage Threshold Failures

Error: Coverage check failed Cause: Test coverage below required thresholds (80% instructions, 95% classes) Solution:

# Check current coverage
mvn jacoco:report

# View coverage report
open target/site/jacoco/index.html

# Add tests for uncovered code
# Focus on instruction coverage first

Prevention: Write tests alongside code, maintain coverage as you develop

Checkstyle Violations

Error: Checkstyle violations found Cause: Code doesn't follow QQQ style rules Solution:

# Check style violations
mvn checkstyle:check

# Fix formatting issues
# Import Kingsrook code style in IntelliJ
# Use auto-format (Cmd+Alt+L on macOS)

# Verify fixes
mvn checkstyle:check

Prevention: Use QQQ IDE configuration, run checkstyle locally before committing

Test Errors

QContext Not Initialized

Error: QContext not initialized Cause: Missing QContext setup in tests Solution:

// ❌ WRONG - Missing context
@Test
void testMyFeature()
{
   // Test without QContext
   action.execute(input);  // Will fail
}

// ✅ CORRECT - Proper context setup
@Test
void testMyFeature()
{
   // BaseTest handles QContext automatically
   super.setUp();
   
   // Your test logic
   action.execute(input);  // Will work
}

Prevention: Always extend BaseTest or manually manage QContext

Memory Backend Not Available

Error: Backend not found: memory Cause: Memory backend not properly configured in tests Solution:

@Test
void testWithMemoryBackend()
{
   // BaseTest provides memory backend automatically
   // If you need custom setup:
   QInstance instance = TestUtils.defineInstance();
   instance.addBackend(new MemoryBackend());
   
   QContext.init(instance, TestUtils.newSession());
   // Your test logic
}

Prevention: Use BaseTest or TestUtils.defineInstance() for test setup

Test Isolation Issues

Error: Tests affecting each other Cause: Shared state between tests Solution:

@BeforeEach
void setUp()
{
   super.setUp();  // BaseTest handles cleanup
   
   // Additional setup if needed
   // Each test gets fresh state
}

@AfterEach
void tearDown()
{
   // BaseTest handles cleanup automatically
   super.tearDown();
}

Prevention: Use BaseTest, avoid static state, clean up in @AfterEach

Runtime Errors

QInstance Not Found

Error: QInstance not found in context Cause: QContext not properly initialized Solution:

// ❌ WRONG - Missing context initialization
public void myMethod()
{
   QInstance instance = QContext.getQInstance();  // Will be null
}

// ✅ CORRECT - Proper context setup
public void myMethod()
{
   QContext.init(instance, session);
   try
   {
      QInstance instance = QContext.getQInstance();  // Will work
      // Your logic
   }
   finally
   {
      QContext.clear();  // Always clean up
   }
}

Prevention: Always initialize QContext before use, clean up in finally block

Backend Module Not Registered

Error: Backend module not found: mymodule Cause: Backend module not properly registered Solution:

// ❌ WRONG - Missing registration
public class MyBackendModule implements QBackendModuleInterface
{
   // Implementation without registration
}

// ✅ CORRECT - Self-registering module
public class MyBackendModule implements QBackendModuleInterface
{
   static
   {
      // Register with QQQ's module system
      QBackendModuleDispatcher.register(new MyBackendModule());
   }
   
   // Implementation
}

Prevention: Always register backend modules in static initialization blocks

Metadata Producer Not Found

Error: Metadata producer not found for type X Cause: Metadata producer not properly configured Solution:

// ❌ WRONG - Missing producer configuration
QInstance instance = new QInstance();
// No metadata producers configured

// ✅ CORRECT - Configure metadata producers
QInstance instance = new QInstance();
instance.addMetaDataProducer(new MyMetaDataProducer());
// Or use MetaDataProducerHelper
MetaDataProducerHelper.populateInstance(instance);

Prevention: Configure metadata producers or use helper methods

Configuration Errors

Environment Variables Missing

Error: Required environment variable not set Cause: Missing required environment configuration Solution:

# Check environment setup
setup-environments.sh --qqq

# Verify .env files exist
ls -la .env*

# Check specific variables
echo $DB_URL
echo $API_KEY

Prevention: Run setup-environments.sh after cloning repository

Database Connection Issues

Error: Database connection failed Cause: Database configuration or connectivity issues Solution:

# Check configuration
qqq:
  database:
    backend: "rdbms"
    connection:
      url: "jdbc:postgresql://localhost:5432/mydb"
      username: "${DB_USERNAME}"
      password: "${DB_PASSWORD}"
      # Add connection pool settings
      pool-size: 10
      timeout: 30s

Prevention: Test database connectivity, use connection pooling, handle timeouts

Port Already in Use

Error: Port 8080 already in use Cause: Another service using the same port Solution:

# Check what's using the port
lsof -i :8080

# Kill the process or change port
kill -9 <PID>

# Or change QQQ port in configuration
qqq:
  server:
    port: 8081  # Use different port

Prevention: Use dynamic port allocation or configure unique ports

IDE Errors

Code Style Not Applied

Error: Code formatting doesn't match QQQ standards Cause: IDE not using QQQ code style Solution:

1. Import code style: qqq-dev-tools/intellij/Kingsrook_Code_Style.xml
2. Import copyright: qqq-dev-tools/intellij/Kingsrook_Copyright_Profile.xml
3. Install plugin: Kingsrook Commentator Plugin
4. Enable auto-format: Actions on Save → Reformat Code

Prevention: Always import QQQ IDE configuration files

Checkstyle Plugin Not Working

Error: Checkstyle violations not showing in IDE Cause: Checkstyle plugin not properly configured Solution:

1. Install plugin: Checkstyle-IDEA
2. Configure rules: Use qqq/checkstyle/config.xml
3. Set scope: Apply to project files
4. Enable real-time: Checkstyle runs as you type

Prevention: Verify plugin installation and configuration

Live Templates Not Available

Error: QQQ live templates not working Cause: Templates not imported Solution:

1. Import templates: qqq-dev-tools/intellij/live-templates/
2. Restart IDE: After importing templates
3. Verify shortcuts: Check template abbreviations
4. Test templates: Try common QQQ patterns

Prevention: Import live templates during initial setup

Performance Issues

Slow Build Times

Error: Builds taking too long Cause: Inefficient build configuration or dependencies Solution:

# Use parallel builds
mvn clean install -T 1C

# Skip tests for faster iteration
mvn clean install -DskipTests

# Build only changed modules
mvn clean install -pl qqq-backend-core

# Use offline mode if dependencies cached
mvn clean install -o

Prevention: Use incremental builds, parallel execution, skip tests during development

Memory Issues

Error: OutOfMemoryError during build Cause: Insufficient memory for Maven Solution:

# Increase Maven memory
export MAVEN_OPTS="-Xmx2g -XX:MaxPermSize=512m"

# Or set in IDE
# IntelliJ → Help → Edit Custom VM Options
-Xmx2g
-XX:MaxPermSize=512m

Prevention: Set appropriate memory limits for your system

Test Timeouts

Error: Tests timing out Cause: Long-running tests or infinite loops Solution:

# Increase test timeout
mvn test -Dtest.timeout=300

# Run specific slow test
mvn test -Dtest=SlowTest#slowMethod

# Profile test execution
mvn test -Dtest.timeout=600

Prevention: Set reasonable timeouts, avoid infinite loops, mock external dependencies

Dependency Issues

Version Conflicts

Error: Dependency convergence errors Cause: Conflicting dependency versions Solution:

# Check dependency tree
mvn dependency:tree

# Resolve conflicts
mvn dependency:resolve

# Update QQQ dependencies
update-all-qqq-deps.sh

# Clean and rebuild
mvn clean install

Prevention: Use QQQ's dependency management tools, avoid version conflicts

Missing Dependencies

Error: Class not found Cause: Missing required dependencies Solution:

<!-- Check pom.xml for missing dependencies -->
<dependency>
    <groupId>com.kingsrook.qqq</groupId>
    <artifactId>qqq-backend-core</artifactId>
    <version>${qqq.version}</version>
</dependency>

<!-- Add missing dependencies -->
<dependency>
    <groupId>missing.group</groupId>
    <artifactId>missing-artifact</artifactId>
    <version>1.0.0</version>
</dependency>

Prevention: Review dependency requirements, use QQQ's module structure

Prevention Strategies

Before Starting Development

1. Verify environment: Java 17+, Maven 3.8+, QQQ dev tools
2. Import IDE config: Code style, copyright, live templates
3. Run initial build: Ensure everything works from start
4. Check documentation: Understand QQQ patterns and standards

During Development

1. Run tests frequently: Catch issues early
2. Check style locally: Run checkstyle before committing
3. Maintain coverage: Write tests as you code
4. Follow patterns: Use established QQQ conventions

Before Committing

1. Full build: mvn clean install
2. Style check: mvn checkstyle:check
3. Test coverage: mvn verify
4. Self-review: Check your code as if reviewing it

Getting Help

When You're Stuck

1. Check this page: Look for similar errors
2. Search issues: Look for reported problems
3. Check logs: Review error details and stack traces
4. Ask community: Use GitHub issues or discussions

Provide Context

When asking for help, include:

• Error message: Exact error text
• Environment: OS, Java version, Maven version
• Steps: How to reproduce the error
• Logs: Relevant log output or stack traces

See Also

• Building Locally - Build issues
• Testing - Testing problems