Skip to main content
Version: 4.6.1-saas

Troubleshooting

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

Installation Issues​

Package Installation Failure​

Symptoms:

  • npm install fails
  • Cannot find package

Solutions:

  1. Check package path: Verify that the dependency path in package.json is correct
  2. Check console: Check the exact URL in the Agent tab of the console
  3. Check network connection: Check internet connection status
  4. Clear npm cache: Run npm cache clean --force and retry

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 initialization location: For Express, verify initialization in app.ts; for Nuxt, verify initialization in middleware

Middleware Issues​

Express Middleware Not Working​

Symptoms:

  • Middleware is not called
  • NetFUNNEL logic is not executed

Solutions:

  1. Check registration: Verify that app.use(netfunnelMiddleware) is correctly called
  2. Check order: Verify that it is registered before other middleware
  3. Check initialization: Verify that Netfunnel.initialize() is called before middleware registration
  4. Check path: To apply to specific paths only, use app.use('/path', netfunnelMiddleware)

Nuxt Middleware Not Working​

Symptoms:

  • Middleware is not called
  • NetFUNNEL logic is not executed

Solutions:

  1. Check file location: Verify that the file is correctly located in server/middleware/netfunnelAgent.ts
  2. Check filename: Verify that the filename is correct
  3. Check initialization: Verify that Netfunnel.initialize() is called within the middleware

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 printLog: true is set

Solutions:

  1. Check settings: Verify that printLog: true is correctly set
  2. Check initialization: Verify that printLog: true is set in Netfunnel.initialize()
  3. Check console: Check logs in the server console

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 printLog: true for debugging:

import { Netfunnel } from 'netfunnel-node-agent';

Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}',
  printLog: true  // Enable debugging logs
});

Check Version​

You can check the agent version:

import { Netfunnel } from 'netfunnel-node-agent';

console.log('NetFUNNEL Version:', Netfunnel.getVersion());

Common Check Items​

  1. Check initialization: Verify that Netfunnel.initialize() is correctly called
  2. Middleware registration: Verify that Express/Nuxt middleware is correctly registered
  3. Trigger rules: Verify that trigger rules are correctly set in the console
  4. Check dependencies: Verify that the netfunnel-node-agent package is correctly installed