Skip to main content
Version: 4.6.1-saas

Troubleshooting

Common issues, solutions, and frequently asked questions for NetFUNNEL Java Agent integration.

Installation Issues​

Library Installation Failure​

Symptoms:

  • Cannot find netfunnel-agent.jar file
  • Dependency addition failure

Solutions:

  1. Check JAR file: Verify that the netfunnel-agent.jar file is in the libs folder
  2. Check dependency path: Verify that the JAR file path is correct in Gradle/Maven configuration
  3. Check external dependencies: Verify that gson and jackson-module-kotlin are correctly added

Initialization Failure​

Symptoms:

  • Error occurs when starting server
  • NetFUNNEL is not initialized

Solutions:

  1. Check clientId: Verify that clientId is correctly set
  2. Check secretKey: Verify that secretKey is correctly set
  3. Check empty strings: Verify that clientId and secretKey are not empty strings
  4. Check build: Verify that the project is correctly built

Interceptor/Filter Issues​

Interceptor Not Working​

Symptoms:

  • Interceptor is not called
  • NetFUNNEL logic is not executed

Solutions:

  1. Check registration: Verify that the addInterceptors method of WebMvcConfigurer is correctly implemented
  2. Check path patterns: Verify that addPathPatterns is correctly set
  3. Check bean registration: Verify that Interceptor is registered with @Component
  4. Check order: Verify that there are no ordering issues with other Interceptors

Filter Not Working​

Symptoms:

  • Filter is not called
  • NetFUNNEL logic is not executed

Solutions:

  1. Check registration: Verify that FilterRegistrationBean is correctly registered
  2. Check URL patterns: Verify that addUrlPatterns is correctly set
  3. Check order: Verify that Filter order is correctly set with setOrder

Trigger Rule Issues​

Trigger Rules Not Matching​

Symptoms:

  • Queue is not applied
  • Waiting room is not displayed even for URLs that match the rules

Solutions:

  1. Check rules: Verify that trigger rules are correctly set in the console
  2. Check URL: Verify that the accessed URL matches the rule's Value
  3. Check Match option: Verify that Match options (Equals, Contains, StartsWith, EndsWith) are correct
  4. Check case sensitivity: Verify the Aa option (case sensitivity) setting
  5. Use test feature: Use the console's trigger rule test feature to verify that URLs match the rules

Waiting Room Not Displayed​

Symptoms:

  • Waiting room is not displayed even for URLs that match the rules
  • Users proceed directly

Solutions:

  1. Check segment activation: Verify that the segment is activated
  2. Check entry status: Verify that entry status is set to Waiting
  3. Check entry limit: Set entry limit to 0 for testing
  4. Check rule matching: Verify that trigger rules are correctly matched

Network and Connection Issues​

Network Connection Error​

Symptoms:

  • Cannot connect to NetFUNNEL server
  • Requests fail

Solutions:

  1. Check connection: Check internet connection status
  2. Check firewall: Verify that NetFUNNEL domain is not blocked
  3. Configure proxy: Configure proxy if necessary
  4. Check server URL: Verify that serverUrl setting is correct

Timeout Error​

Symptoms:

  • Requests timeout
  • No response received

Solutions:

  1. Check network status: Check network connection status
  2. Check server status: Check NetFUNNEL server status
  3. Check settings: Verify that initialization settings are correct

Logging Issues​

Logs Not Output​

Symptoms:

  • Logs are not output even though log level is set

Solutions:

  1. Check dependency: Verify that logback-classic dependency is added
  2. Check log level: Verify that logLevel setting is correct
  3. Check log configuration: Check logback.xml or logback-spring.xml configuration

Key Management Issues​

Key Not Returned​

Symptoms:

  • Next user waits indefinitely
  • Queue does not progress

Solutions:

  1. Check returnKey setting: Verify that returnKey setting is correct
  2. Check timeout: Check segment timeout settings
  3. Check server logs: Check server logs for key return related errors

Debugging Tips​

Check Logs​

You can check logs by setting logLevel for debugging:

import ch.qos.logback.classic.Level;

NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
    .clientId("{{CLIENT_ID}}")
    .secretKey("{{SECRET_KEY}}")
    .logLevel(Level.DEBUG)  // Enable debugging logs
    .build();

Common Check Items​

  1. Check initialization: Verify that NetFunnelInitialize is correctly created
  2. Interceptor/Filter registration: Verify that Interceptor/Filter is correctly registered
  3. Trigger rules: Verify that trigger rules are correctly set in the console
  4. Check dependencies: Verify that all required dependencies are correctly added