Skip to main content
Version: 4.6.1-saas

Troubleshooting & FAQ

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

Installation Issues​

Agent Script Not Loading​

Symptoms:

  • No netfunnel-javascript-agent.js in Network tab
  • HTTP 404 or other errors for agent file

Solutions:

  1. Check script URL: Verify the src URL is correct and accessible
  2. Network connectivity: Ensure your server can reach NetFUNNEL servers
  3. Ad blockers: Disable ad blockers that might block the script
  4. Script placement: Move script to very top of <head> tag
<!-- Correct placement -->
<head>
  <script src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js" data-nf-client-id="your-client-id"></script>
  <!-- other scripts -->
</head>

Settings File Not Loading​

Symptoms:

  • No nf-setting.json in Network tab
  • HTTP errors for settings file

Solutions:

  1. Check data-nf-client-id: Verify the client ID is correct
  2. Console access: Ensure you have proper access to NetFUNNEL console
  3. Segment activation: Verify your segment is activated in console

Bypass Mode (No Waiting Room)​

Symptoms:

  • Users access pages directly without waiting room
  • No NetFUNNEL traffic control

Solutions:

  1. Required attributes: Ensure data-nf-client-id is present
  2. Segment activation: Check segment is activated in console
  3. Limited Inflow: Verify Limited Inflow is not set to unlimited
  4. Trigger rules: Confirm trigger rules match your URLs correctly

Function Call Errors​

"nfStart is not a function" Error​

Symptoms:

  • ReferenceError: nfStart is not defined
  • Functions undefined when called

Solutions:

  1. Function availability check: Always check if functions exist before calling
if (typeof window.nfStart === 'function') {
  nfStart(keys, callback);
} else {
  // Fallback logic
  console.log('NetFUNNEL not available');
}
  1. Script loading order: Ensure NetFUNNEL script loads before your code
  2. Wait for load: Call functions after window.load event
window.addEventListener('load', function() {
  // Safe to call NetFUNNEL functions here
});

Callback Not Executing​

Symptoms:

  • nfStart called but callback never fires
  • No response received

Solutions:

  1. Check network: Verify network requests to NetFUNNEL server
  2. Console logs: Enable data-nf-print-log="true" for debugging
  3. Segment status: Ensure segment is not in Block state
  4. Limited Inflow: Check if Limited Inflow allows entry

Network & Connection Issues​

Network Timeout Errors​

Symptoms:

  • NetworkError with status code 1002
  • Requests timing out

Solutions:

  1. Increase timeout: Set data-nf-network-timeout to higher value (max 10000ms)
  2. Retry configuration: Increase data-nf-retry-count
  3. Network recovery: Enable data-nf-use-network-recovery-mode="true"
<script
  src="https://agent-lib.stclab.com/agents/client/javascript/netfunnel-javascript-agent.js"
  data-nf-client-id="your-client-id"
  data-nf-network-timeout="5000"
  data-nf-retry-count="2"
  data-nf-use-network-recovery-mode="true"
></script>

Network Not Connected Errors​

Symptoms:

  • NetworkError with status code 1001
  • No internet connectivity

Solutions:

  1. Check connectivity: Verify internet connection
  2. Firewall: Ensure NetFUNNEL domains are not blocked
  3. Proxy settings: Configure proxy if needed
  4. Error handling: Implement proper NetworkError handling
function nfCallback(response) {
  if (response.status === 'NetworkError') {
    // Show user-friendly message
    alert('Network connection issue. Please check your internet connection.');
    // Optionally retry or proceed anyway
  }
}

Waiting Room Issues​

Waiting Room Not Displaying​

Symptoms:

  • No waiting room appears
  • Users proceed directly

Solutions:

  1. Limited Inflow: Set to 0 for testing
  2. Segment activation: Ensure segment is activated
  3. Trigger rules: Verify URL matching rules
  4. Template settings: Check data-nf-use-netfunnel-template="true"

Waiting Room Stuck (Never Ends)​

Symptoms:

  • Waiting room appears but never allows entry
  • Infinite waiting

Solutions:

  1. Limited Inflow: Increase Limited Inflow value
  2. Segment status: Check if segment is in Block state
  3. Network issues: Verify network connectivity
  4. Server status: Check NetFUNNEL server status

Symptoms:

  • Code-based integration shows no modal
  • Page redirects instead

Solutions:

  1. Integration method: Ensure you're using code-based, not URL-triggered
  2. Function calls: Verify nfStart is called correctly
  3. Callback handling: Check callback is implemented
  4. Template settings: Ensure data-nf-use-netfunnel-template="true"

Key Management Issues​

Key Not Returned​

Symptoms:

  • Next users remain waiting indefinitely
  • Queue doesn't progress

Solutions:

  1. Always call nfStop: Ensure nfStop/nfStopSection is called
  2. Error handling: Return key even in error scenarios
  3. Timeout settings: Check segment timeout settings
  4. Function matching: Use identical keys for start/stop
// Always return key
try {
  performAction();
  nfStop(keys); // Success case
} catch (error) {
  nfStop(keys); // Error case - still return key
}

Key Mismatch Errors​

Symptoms:

  • Server errors about invalid keys
  • Key not found errors

Solutions:

  1. Key consistency: Use identical keys for start/stop functions
  2. Key scope: Don't reuse keys across different actions
  3. Timing: Don't call stop before start completes
// Correct: Same keys for start and stop
const keys = { projectKey: 'service_1', segmentKey: 'segKey_123' };
nfStart(keys, callback);
nfStop(keys);

Configuration Issues​

Wrong Project/Segment Keys​

Symptoms:

  • Functions called but no effect
  • Wrong segment behavior

Solutions:

  1. Console verification: Double-check keys in NetFUNNEL console
  2. Copy exactly: Copy keys exactly as shown in console
  3. Environment: Ensure using correct environment (prod vs staging)

Data Attributes Not Working​

Symptoms:

  • Configuration options not taking effect
  • Unexpected behavior

Solutions:

  1. Attribute format: Use correct format (e.g., data-nf-timeout="5000")
  2. Value ranges: Ensure values are within allowed ranges
  3. Method compatibility: Check if attribute applies to your integration method

Browser & Environment Issues​

Ad Blocker Interference​

Symptoms:

  • Scripts blocked
  • Network requests blocked

Solutions:

  1. Whitelist domains: Add NetFUNNEL domains to ad blocker whitelist
  2. User instructions: Provide instructions for users
  3. Fallback handling: Implement graceful degradation

Browser Compatibility​

Symptoms:

  • Functions not working in certain browsers
  • JavaScript errors

Solutions:

  1. Browser support: Check browser compatibility
  2. Polyfills: Add necessary polyfills for older browsers
  3. Feature detection: Use feature detection before calling functions

Development vs Production​

Symptoms:

  • Works in development but not production
  • Different behavior between environments

Solutions:

  1. Environment URLs: Use correct URLs for each environment
  2. Console configuration: Set up separate segments for dev/prod
  3. Caching: Clear browser cache and CDN cache

Getting Help​

If you're still experiencing issues:

  1. Check console logs: Enable data-nf-print-log="true" and check browser console
  2. Verify configuration: Double-check all settings in NetFUNNEL console
  3. Test with simple setup: Start with basic configuration and add complexity gradually
  4. Contact support: Reach out to NetFUNNEL support with specific error details