Troubleshooting¶

This guide helps you diagnose and resolve common issues when using Forage.

Quick Diagnostics¶

Before diving into specific issues, try these diagnostic steps:

# Validate properties without running
camel run * --strict

# Enable debug logging
camel run * --logging-level=DEBUG

# Check Forage plugin installation
camel plugin list | grep forage

Common Configuration Issues¶

Missing Required Properties¶

Error:

MissingConfigException: Missing required configuration: forage.myDb.jdbc.url

Causes: - Property not set in any configuration source - Typo in property name - Wrong file location

Solutions:

1. Check property naming:

   # Wrong
   forage.myDb.jdbc.ur=jdbc:postgresql://localhost:5432/db
   
   # Correct
   forage.myDb.jdbc.url=jdbc:postgresql://localhost:5432/db
   

2. Verify file location:

3. Properties files must be in the working directory
4. Or set FORAGE_CONFIG_DIR environment variable

5. Or include in classpath

6. Check environment variable format:

   # Wrong
   export forage.myDb.jdbc.url=jdbc:postgresql://localhost:5432/db
   
   # Correct
   export FORAGE_MYDB_JDBC_URL=jdbc:postgresql://localhost:5432/db
   

Property Typos and Unknown Properties¶

Error:

[UNKNOWN_PROPERTY] Unknown property 'usernam' for factory 'jdbc'. Did you mean 'username'?

Solution:

Use property validation to catch typos before runtime:

# Validate and show suggestions
camel run * --strict

The validator uses Levenshtein distance to suggest corrections. See the Property Validation guide for details.

Bean Reference Errors¶

Error:

No bean found with name 'myDatabase'

Causes: - Bean name doesn't match property prefix - Provider not on classpath - ServiceLoader registration missing

Solutions:

1. Verify bean name matches prefix:

   # Bean name is "myDatabase"
   forage.myDatabase.jdbc.url=jdbc:postgresql://localhost:5432/db
   

# Reference must match exactly
- to:
    uri: sql
    parameters:
      dataSource: "#myDatabase"  # Must match prefix

1. Check provider dependency:

   <!-- Required for PostgreSQL -->
   <dependency>
       <groupId>io.kaoto.forage</groupId>
       <artifactId>forage-jdbc-postgresql</artifactId>
       <version>1.1</version>
   </dependency>
   

Runtime-Specific Issues¶

Camel JBang¶

Plugin Not Found¶

Error:

Unknown command: forage

Solution:

Install or reinstall the plugin:

camel plugin add forage --gav io.kaoto.forage:camel-jbang-plugin-forage:1.1

Verify installation:

camel plugin list | grep forage

Dependencies Not Resolved¶

Error:

ClassNotFoundException: io.kaoto.forage.jdbc.postgresql.PostgresqlJdbc

Cause: - No forage.* properties in configuration files - Plugin not detecting properties

Solution:

1. Ensure properties file exists with forage.* keys
2. Run from directory containing properties files
3. Check plugin is installed: camel plugin list

Spring Boot¶

Beans Not Auto-Configured¶

Error:

No qualifying bean of type 'javax.sql.DataSource' available

Causes: - Missing starter dependency - AutoConfiguration.imports not found - Properties not in Spring Environment

Solutions:

1. Add starter dependency:

   <dependency>
       <groupId>io.kaoto.forage</groupId>
       <artifactId>forage-jdbc-starter</artifactId>
       <version>1.1</version>
   </dependency>
   

2. Check auto-configuration:

   # Enable debug logging
   java -jar app.jar --debug
   

Look for ForageDataSourceAutoConfiguration in output.

1. Verify properties location:
2. Must be in application.properties or application.yml
3. Or use @PropertySource to load custom files

Property Precedence Issues¶

Issue: Spring Environment properties override Forage ConfigStore.

Expected behavior: 1. Environment variables (highest) 2. System properties 3. Spring application.properties 4. Forage properties files (lowest)

Solution:

Use Spring's property syntax in application.properties:

# Spring Boot style
forage.myDb.jdbc.url=${DATABASE_URL:jdbc:postgresql://localhost:5432/db}
forage.myDb.jdbc.username=${DB_USER:admin}

Debugging Techniques¶

Enable Debug Logging¶

# Camel JBang
camel run * --logging-level=DEBUG

# Spring Boot
java -jar app.jar --logging.level.io.kaoto.forage=DEBUG

# Quarkus
mvn quarkus:dev -Dquarkus.log.category."io.kaoto.forage".level=DEBUG

Inspect Camel Registry¶

// List all beans
camelContext.getRegistry().findByType(DataSource.class)
    .forEach((name, bean) -> 
        System.out.println("Bean: " + name + " = " + bean));

// Lookup specific bean
DataSource ds = camelContext.getRegistry()
    .lookupByNameAndType("myDb", DataSource.class);

Validate Properties¶

# Strict mode - fail on warnings
camel run * --strict

# Show all warnings
camel run *  # Warnings printed but doesn't fail

Camel JBang Debugging¶

For Java debugging and standard JBang debugging techniques, see the Camel JBang documentation.

Getting Help¶

If you're still stuck after trying these solutions:

1. Check the documentation:
2. Core Concepts
3. Configuration System

4. Module-specific docs

5. Search existing issues:

6. GitHub Issues

7. Ask for help:

8. GitHub Discussions

9. Include error messages, configuration, and Forage version

10. Report a bug:

11. Create an issue
12. Include minimal reproducible example