Skip to main content
Version: 4.6.1-saas

Troubleshooting

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

Installation Issues​

Package Installation Failure​

Symptoms:

  • flutter pub get fails
  • Package not found

Solutions:

  1. Check network connection: Verify internet connection status
  2. Check package path: Verify that the dependency path in pubspec.yaml is correct
  3. Check tar.gz file: Verify that the tar.gz file is in the correct location
  4. Check indentation: Verify that the indentation in the pubspec.yaml file is correct

Initialization Failure​

Symptoms:

  • Error occurs when app starts
  • NetFUNNEL is not initialized

Solutions:

  1. Check clientId: Verify that clientId is set correctly
  2. Check empty string: Verify that clientId is not an empty string
  3. Initialization location: Verify that initialization is done at the start of the main() function in main.dart
  4. Check async/await: Verify that the main() function is declared as async and uses await

Function Call Errors​

"nfStart is not a function" Error​

Symptoms:

  • NoSuchMethodError: The method 'nfStart' was called on null
  • Function is undefined when called

Solutions:

  1. Check initialization: Verify that Netfunnel.instance.initialize() was called first
  2. Check import: Verify that import 'package:netfunnel_flutter/netfunnel_flutter.dart' is correct
  3. Function usage: Verify that it is called in the format Netfunnel.instance.nfStart()

Callback Not Executing​

Symptoms:

  • nfStart is called but callback is not executed
  • No response received

Solutions:

  1. Check network: Verify network requests to NetFUNNEL server
  2. Console logs: Set printLog: true to check debugging logs
  3. Segment status: Verify that the segment is not in Block status
  4. Entry allowance: Verify that entry allowance allows entry

Network and Connection Issues​

Network Timeout Error​

Symptoms:

  • onNetworkError status code 1002
  • Request times out

Solutions:

  1. Increase timeout: Set networkTimeout to a higher value (max 10000ms)
  2. Configure retry: Increase retryCount
  3. Network recovery: Enable useNetworkRecoveryMode: true
await Netfunnel.instance.initialize(
  clientId: 'your-client-id',
  networkTimeout: 5000,
  retryCount: 2,
  useNetworkRecoveryMode: true,
);

Network Connection Error​

Symptoms:

  • onNetworkError status code 1001
  • No internet connection

Solutions:

  1. Check connection: Verify internet connection status
  2. Firewall: Verify that NetFUNNEL domain is not blocked
  3. Proxy settings: Configure proxy if necessary
  4. Error handling: Implement appropriate NetworkError handling
class NetfunnelHandler extends NetfunnelCallback {
  @override
  void onNetworkError(int statusCode, String message) {
    // Display user-friendly message
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('Network Connection Issue'),
        content: Text('Please check your internet connection.'),
      ),
    );
    // Optionally retry or continue
  }
}

HTTP Communication Error​

Symptoms:

  • Error occurs during HTTP communication
  • HTTPS communication works normally

Solutions:

The NetFUNNEL Flutter agent recommends HTTPS communication by default. When using HTTP communication, you can allow HTTP communication through platform-specific settings.

Android:

Create android/app/src/main/res/xml/network_security_config.xml file:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">{{DOMAIN_URL}}</domain>
    </domain-config>
</network-security-config>

Add configuration to android/app/src/main/AndroidManifest.xml:

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >
</application>

iOS:

Add configuration to ios/Runner/Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

Waiting Room Issues​

Waiting Room Not Displayed​

Symptoms:

  • Waiting room does not appear
  • User proceeds directly

Solutions:

  1. Entry allowance: Set to 0 for testing
  2. Segment activation: Verify that the segment is activated
  3. Template settings: Verify useNetfunnelTemplate: true
  4. Callback implementation: Verify that required callback functions (onSuccess, onError, onNetworkError) are implemented

Waiting Room Stuck (Does Not End)​

Symptoms:

  • Waiting room appears but entry is not allowed
  • Infinite waiting

Solutions:

  1. Entry allowance: Increase entry allowance value
  2. Segment status: Verify that the segment is in Block status
  3. Network issues: Verify network connection status
  4. Server status: Verify NetFUNNEL server status

Key Management Issues​

Key Not Returned​

Symptoms:

  • Next user waits indefinitely
  • Queue does not progress

Solutions:

  1. nfStop call: Always verify that nfStop/nfStopSection is called
  2. Error handling: Return key even in error scenarios
  3. Check timeout: Verify segment timeout settings
try {
  await performAction();
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
} catch (error) {
  print('Operation failed: $error');
  // Return key even on error
  await Netfunnel.instance.nfStop(
    projectKey: projectKey,
    segmentKey: segmentKey,
  );
}

Debugging Tips​

Check Logs​

You can check logs by setting printLog: true for debugging:

await Netfunnel.instance.initialize(
  clientId: 'your-client-id',
  printLog: true,  // Enable debugging logs
);

Check logs with [NF4] prefix in Flutter console.

Check Agent Version​

You can use the getVersion() function to check the agent's version:

String version = Netfunnel.instance.getVersion();
print('NetFUNNEL Agent version: $version');

Common Checkpoints​

  1. Check initialization: Verify that Netfunnel.instance.initialize() is called correctly
  2. Callback implementation: Verify that required callback functions (onSuccess, onError, onNetworkError) are implemented
  3. Key matching: Verify that the same keys are used in start and stop functions
  4. BuildContext: Verify that a valid BuildContext is passed when calling nfStart/nfStartSection