Troubleshooting & Common Errors

Error: Could Not Find Configuration File

Error Message:

IllegalStateException: Could not find detect-cli.properties on classpath

Cause: Configuration properties file is missing or not on the classpath.

Solution:

  1. Verify file exists:
    
   # Windows
   dir %HCL_UNICA_DETECT_HOME%\tools\conf\detect-cli.properties
   
   # Linux
   ls $HCL_UNICA_DETECT_HOME/tools/conf/detect-cli.properties
  2. Check classpath in wrapper script:
    • Open CliTool.bat (Windows) or CliTool.sh (Linux)
    • Verify CLASSPATH includes the tools/conf directory
  3. Rebuild CLI:
    
   cd tools/detect-cli
   ./gradlew clean build

Error: Connection Timeout

Error Message:

Error retrieving datasource names: Connection timeout - Unable to reach Platform at http://default.hcl.in:5001/unica

or

Error retrieving kafka cluster names: SocketTimeoutException: Read timed out

Cause: Network connectivity issues or services not running.

Solution:

  1. Verify Platform is running:
    
   curl -v http://default.hcl.in:5001/unica/health
  2. Verify Detect is running:
    
   curl -v http://default.hcl.in:8080/detect/public/api/health_check
  3. Check firewall settings:
    • Ensure ports 5001 (Platform) and 8080 (Detect) are not blocked
    • Check if corporate firewall/proxy requires special configuration
  4. Verify hostname resolution:
    
   # Windows
   ping default.hcl.in
   
   # Linux
   ping -c 4 default.hcl.in
  5. Check /etc/hosts (Linux) or C:\Windows\System32\drivers\etc\hosts (Windows):
    
   127.0.0.1   default.hcl.in
  6. Increase timeout values in detect-cli.properties:
    
   cli.connectionTimeoutMillis=60000
   cli.socketTimeoutMillis=60000

Error: Unauthorized (401)

Error Message:

HTTP 401 Unauthorized - Invalid OAuth2 token

or

Error retrieving kafka cluster names: Unauthorized

Cause: OAuth2 credentials are invalid, expired, or not configured.

Solution:

  1. Verify credentials are configured in detect-cli.properties:
    
   platform.clientId=333842
   platform.clientSecret=c3xzOPhy5KeYubl
  2. Regenerate OAuth2 credentials:
    
   # Windows
   cd %UNICA_PLATFORM_HOME%\tools\bin
   clientDetails.bat -a Manager
   
   # Linux
   cd $UNICA_PLATFORM_HOME/tools/bin
   ./clientDetails.sh -a Manager
  3. Update properties file with new credentials
  4. Verify user ID is correct:
    
   platform.userid=asm_admin

    User must exist in Platform and have API access permissions

  5. Check Platform logs for authentication errors:
    1. %UNICA_PLATFORM_HOME%\logs\unica_platform.log (Windows)
    2. $UNICA_PLATFORM_HOME/logs/unica_platform.log (Linux)

Error: Forbidden (403)

Error Message:

HTTP 403 Forbidden - Insufficient permissions

Cause: User lacks permissions to access configuration endpoints.

Solution:

  1. Verify user has required role:
    • Log into Platform UI as admin
    • Navigate to: Settings ' Users and Security ' Users
    • Select the user (e.g., asm_admin)
    • Verify user has Admin or Configuration Manager role
  2. Grant API access permissions:
    • Settings ' Users and Security ' Roles
    • Edit the user's role
    • Enable "API Access" permission
    • Enable "Configuration Read" permission
  3. Use a different user with appropriate permissions:
    
   platform.userid=platform_admin
  4. Check Detect API security configuration in Platform:
    • Settings ' Configuration ' Detect ' API Security
    • Verify configuration endpoints are not restricted

Error: Connection Refused

Error Message:

Error retrieving datasource names: Connection refused - Detect backend is not reachable

or

java.net.ConnectException: Connection refused: connect

Cause: Detect backend or Platform service is not running.

Solution:

  1. Start Platform:
    
   # Windows
   cd %UNICA_PLATFORM_HOME%\bin
   startserver.bat
   
   # Linux
   cd $UNICA_PLATFORM_HOME/bin
   ./startserver.sh
  2. Start Detect (Tomcat):
    
   # Windows
   cd %CATALINA_HOME%\bin
   startup.bat
   
   # Linux
   cd $CATALINA_HOME/bin
   ./startup.sh
  3. Verify services are running:
    
   # Check Platform
   curl http://default.hcl.in:5001/unica/health
   
   # Check Detect
   curl http://default.hcl.in:8080/detect/public/api/health_check
  4. Check service logs for startup errors:
    • Platform: %UNICA_PLATFORM_HOME%\logs\unica_platform.log
    • Detect: %CATALINA_HOME%\logs\catalina.out or %CATALINA_HOME%\logs\detect.log

Error: Unknown Host

Error Message:

java.net.UnknownHostException: default.hcl.in

Cause: Hostname cannot be resolved by DNS or hosts file.

Solution:

  1. Add hostname to hosts file:
    Windows: Edit C:\Windows\System32\drivers\etc\hosts (requires Administrator)
    127.0.0.1   default.hcl.in

    Linux : Edit /etc/hosts (requires sudo)

    127.0.0.1   default.hcl.in
  2. Or use IP address directly in detect-cli.properties:
    
   platform.baseUrl=http://127.0.0.1:5001/unica
   detect.baseUrl=http://127.0.0.1:8080/detect
  3. Or use actual hostname:
    
   platform.baseUrl=http://myserver.company.com:5001/unica
   detect.baseUrl=http://myserver.company.com:8080/detect

Error: Found 0 Datasources (But You Know They Exist)

Output:

Found 0 datasources:
[]

Cause: User permission issue or datasources not properly configured.

Solution:

  1. Verify datasources exist in Platform:
    • Log into Platform UI
    • Navigate to: Settings ' Configuration ' Data Sources
    • Confirm datasources are listed
  2. Check user permissions:
    • Settings ' Users and Security ' Users
    • Select user (asm_admin or configured platform.userid)
    • Verify "Datasource Access" permissions
    • Grant read permissions on specific datasources if needed
  3. Try with Platform admin user:
    platform.userid=platform_admin

  4. If this works, original user lacks datasource permissions

    Check Detect-Platform integration:
    # Re-run Platform integration
   cd %UNICA_PLATFORM_HOME%\tools\bin
   populateDb.bat -n UnicaDetect
  5. Verify Detect backend logs for Platform communication errors:
    tail -f %CATALINA_HOME%/logs/detect.log | grep -i "datasource"

Error: Found 0 Kafka Clusters (But You Know They Exist)

Output:

Found 0 kafka clusters:
[]

Cause: Kafka clusters not configured in Platform or integration issue.

Solution:

  1. Verify Kafka clusters exist in Platform:
    • Log into Platform UI
    • Navigate to: Settings ' Configuration ' Affinium ' UnicaDetect ' Kafka Clusters
    • Confirm clusters are configured with names and bootstrap servers
  2. Check Platform Kafka configuration structure:
    • Platform stores Kafka configs under: Affinium|UnicaDetect|kafkaClusters|<cluster-name>
    • Each cluster should have bootstrap.servers property at minimum
  3. Re-register Detect Kafka configuration in Platform:
    
   cd %UNICA_PLATFORM_HOME%\tools\bin
   configTool.bat -vp -p "Affinium|UnicaDetect" -f "%HCL_UNICA_DETECT_HOME%\conf\web\platform\UnicaDetect_kafka_cluster_configuration.xml"
  4. Restart Detect backend to reload Platform configurations:
    
   # Windows
   cd %CATALINA_HOME%\bin
   shutdown.bat
   startup.bat
   
   # Linux
   cd $CATALINA_HOME/bin
   ./shutdown.sh
   ./startup.sh
  5. Check Detect logs for configuration loading:
    
   grep -i "kafka" %CATALINA_HOME%/logs/detect.log

Error: No Main Manifest Attribute

Error Message:

no main manifest attribute, in detect-cli.jar

Cause: JAR file is not properly built or manifest is missing.

Solution:

  1. Rebuild the CLI:
    
   cd tools/detect-cli
   ./gradlew clean build
  2. Verify JAR contains manifest:
    
   # Windows
   jar tf build\libs\detect-cli.jar | findstr MANIFEST.MF
   
   # Linux
   jar tf build/libs/detect-cli.jar | grep MANIFEST.MF
  3. Check manifest contents:
    
   unzip -p build/libs/detect-cli.jar META-INF/MANIFEST.MF
    Should contain:
    
   Main-Class: com.hcl.unica.detect.cli.CLIMain
  4. If using Gradle application plugin, ensure build.gradle.kts has:
    
   application {
       mainClass.set("com.hcl.unica.detect.cli.CLIMain")
   }
   
   tasks.jar {
       manifest {
           attributes("Main-Class" to "com.hcl.unica.detect.cli.CLIMain")
       }
   }

Error: ClassNotFoundException

Error Message:

Exception in thread "main" java.lang.ClassNotFoundException: com.hcl.unica.detect.cli.CLIMain

Cause: Main class not found in JAR or classpath issue.

Solution:

  1. Verify JAR is a fat JAR (contains all dependencies):
    
   # Check JAR size - should be several MB if it includes dependencies
   # Windows
   dir build\libs\detect-cli.jar
   
   # Linux
   ls -lh build/libs/detect-cli.jar
  2. Rebuild with dependencies:
    
   cd tools/detect-cli
   ./gradlew clean build
  3. Verify composite build is working:
    
   ./gradlew :detect-cli:dependencies --configuration runtimeClasspath

    Should show detect-client and other modules

  4. Check if main class exists in JAR:
    
   jar tf build/libs/detect-cli.jar | grep CLIMain.class

    Should output: com/hcl/unica/detect/cli/CLIMain.class

Error: JSON Processing Exception (For Other Commands)

Error Message:

JsonParseException: Unexpected character ('}' (code 125))

Cause: Malformed JSON in payload file.

Solution:

  1. Validate JSON syntax using online validator: https://jsonlint.com/
  2. Common JSON issues:
    • Missing commas between fields
    • Trailing commas in arrays or objects
    • Unescaped quotes in string values
    • Incorrect bracket/brace matching
  3. Use proper encoding (UTF-8 without BOM):

   # Windows - save file as UTF-8 in Notepad
   # Linux - most editors default to UTF-8

Error: Invalid Argument Count

Error Message:

IllegalArgumentException: Invalid number of arguments for command 'get-all-datasource-names-for-logged-in-user'. Expected 0, got 2.

Cause: Extra arguments passed to a command that doesn't accept any.

Solution:

Correct syntax for configuration commands:


# " Correct - No arguments
./CliTool.sh get-all-datasource-names-for-logged-in-user

#  -  Wrong - Don't add arguments
./CliTool.sh get-all-datasource-names-for-logged-in-user -f file.json

Summary:

  • get-all-datasource-names-for-logged-in-user ' 0 arguments
  • get-all-kafka-cluster-names ' 0 arguments

Error: Service Unavailable (503)

Error Message:

Error retrieving kafka cluster names: HTTP 503 Service Unavailable

Cause: Detect backend is starting up or experiencing issues.

Solution:

  1. Wait 30-60 seconds for Detect to fully start
  2. Check Detect logs:
    
   tail -f %CATALINA_HOME%/logs/detect.log

    Look for:

    • Spring Boot initialization messages
    • "Started DetectWebApplication" message
    • Database connection errors
  3. Verify database connectivity:
    • Ensure MariaDB is running
    • Check database connection in %CATALINA_HOME%/conf/Catalina/localhost/detect.xml
  4. Check Tomcat status:
    
   # Windows
   %CATALINA_HOME%\bin\catalina.bat version
   
   # Linux
   $CATALINA_HOME/bin/catalina.sh version

Warning: Empty Results When Data Expected

Scenario: You know datasources/clusters exist but get empty results.

Debugging Steps:

  1. Enable debug logging (if supported):
    
   export DETECT_CLI_DEBUG=true
   ./CliTool.sh get-all-datasource-names-for-logged-in-user
  2. Test with curl directly:
    
   # Get OAuth2 token first
   TOKEN=$(curl -X POST http://default.hcl.in:5001/unica/oauth/token \
     -d "client_id=333842" \
     -d "client_secret=c3xzOPhy5KeYubl" \
     -d "grant_type=client_credentials" | jq -r '.access_token')
   
   # Test datasources endpoint
   curl -H "Authorization: Bearer $TOKEN" \
     http://default.hcl.in:8080/detect/api/unicadetect/v1/configuration/datasources
  3. Check Platform configuration registry:
    • Log into Platform UI
    • Settings ' Configuration ' Data Sources
    • Verify datasources are registered
    • Check datasource names don't have special characters
  4. Review user permissions in Platform:
    • Settings ' Users and Security
    • Verify user exists and is active
    • Check role assignments