Troubleshooting

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NapNeko/NapCatQQ/llms.txt

Use this file to discover all available pages before exploring further.

​

Common Issues

​

Login Issues

​

Cannot Login / Login Timeout

• Login process hangs or times out
• QR code doesn’t appear
• “Login failed” error message

1. Check NTQQ version compatibility
   • Ensure you’re using a compatible NTQQ version
   • Download the latest version from the Release page
2. Clear login cache
   • Close NapCat and NTQQ completely
   • Delete the login cache directory
   • Restart and try logging in again
3. Check network connectivity
   • Ensure you have a stable internet connection
   • Try disabling VPN or proxy temporarily
   • Check if QQ servers are accessible
4. Update NapCat
   • Older versions may have login compatibility issues
   • Always use the latest stable release

​

Account Frozen After Login

• Login succeeds but account gets frozen
• “Account at risk” warning

1. Use official QQ app for verification
   • Login to the official QQ mobile app
   • Complete any security verifications
   • Try NapCat again after verification
2. Avoid frequent logins
   • Don’t login/logout repeatedly in short time
   • Wait at least 5-10 minutes between attempts
3. Use stable environment
   • Login from the same IP address consistently
   • Avoid using public or frequently changing IPs

​

Connection Issues

​

WebSocket Connection Refused

• Error: connect ECONNREFUSED
• WebSocket client cannot connect

1. Verify server is running
   # Check if port is listening
   netstat -an | grep 3001
   # or
   lsof -i :3001
   
2. Check configuration
   {
     "network": {
       "websocketServers": [{
         "enable": true,  // Must be true
         "host": "127.0.0.1",
         "port": 3001
       }]
     }
   }
   
3. Check firewall settings
   • Allow the port through firewall
   • On Linux: sudo ufw allow 3001
   • On Windows: Add firewall rule for the port
4. Verify host binding
   • Use 0.0.0.0 to listen on all interfaces
   • Use 127.0.0.1 for localhost only
   • Make sure client connects to the correct host

​

HTTP API Returns 403 Forbidden

• API calls return 403 status code
• {"message": "token verify failed!"}

1. Check authentication token
   # Correct format
   curl -H "Authorization: Bearer your_token" http://localhost:3000/get_login_info
   
   # Or use query parameter
   curl "http://localhost:3000/get_login_info?access_token=your_token"
   
2. Verify token in config
   • Ensure token matches exactly (case-sensitive)
   • Check for extra spaces or quotes
   • If token is empty in config, don’t send token in request
3. Check WebSocket authentication
   // Include token in URL
   const ws = new WebSocket('ws://localhost:3001/?access_token=your_token');
   
   // Or in headers
   const ws = new WebSocket('ws://localhost:3001/', {
     headers: { 'Authorization': 'Bearer your_token' }
   });
   

​

Reverse WebSocket Not Connecting

• 反向WebSocket连接错误
• 在 5 秒后尝试重新连接

1. Verify target server is running
   • Ensure your WebSocket server is running and listening
   • Check server logs for connection attempts
2. Check URL format
   {
     "url": "ws://localhost:8082"  // Correct
     // Not: "http://localhost:8082"
     // Not: "ws://localhost:8082/"
   }
   
3. Test with a simple WebSocket server
   const WebSocket = require('ws');
   const wss = new WebSocket.Server({ port: 8082 });
   
   wss.on('connection', (ws, req) => {
     console.log('Client connected');
     console.log('Headers:', req.headers);
   });
   
   console.log('Server listening on port 8082');
   

​

Event and Message Issues

​

Not Receiving Events

• WebSocket connected but no events received
• Messages sent but no notification

1. Check connection type
   • Connect to / for events (not /api)
   • /api endpoint is only for API calls
   // Correct for events
   const ws = new WebSocket('ws://localhost:3001/');
   
   // Wrong - this is for API calls only
   const ws = new WebSocket('ws://localhost:3001/api');
   
2. Verify bot is online
   • Check WebUI or logs to confirm bot is logged in
   • Look for lifecycle event after connection
3. Check event filters
   • Verify reportSelfMessage setting if expecting self-messages
   • Check if events are filtered by your application
4. Monitor debug logs
   {
     "debug": true  // Enable debug logging
   }
   

​

Messages Not Sending

• API returns success but message not delivered
• “Send message failed” error

1. Check API response
   {
     "status": "ok",
     "retcode": 0,
     "data": {
       "message_id": 12345  // Message ID confirms success
     }
   }
   
2. Verify message format
   {
     "action": "send_private_msg",
     "params": {
       "user_id": 12345678,  // Must be number
       "message": "Hello"    // Can be string or array
     }
   }
   
3. Check user/group ID
   • Ensure user ID exists and bot has permission
   • For groups, verify bot is a member
   • For private messages, must be friend or in same group
4. Check message content
   • Some message types may be restricted
   • Try sending a simple text message first
   • Check for invalid CQ codes

​

Webhook Not Receiving Events

• HTTP client configured but webhook server receives nothing
• No POST requests arriving

1. Verify HTTP client is enabled
   {
     "network": {
       "httpClients": [{
         "enable": true,  // Must be true
         "url": "http://localhost:8080"
       }]
     }
   }
   
2. Check webhook URL accessibility
   # Test if webhook endpoint is reachable
   curl -X POST http://localhost:8080 \
     -H "Content-Type: application/json" \
     -d '{"test": "data"}'
   
3. Check server logs
   • Look for [Http Client] errors in NapCat logs
   • Check webhook server logs for incoming requests
4. Verify network path
   • If using localhost, ensure both run on same machine
   • Check firewall rules
   • Test with public IP or ngrok for debugging

​

Configuration Issues

​

Configuration Not Loading

• Changes to config file have no effect
• Bot uses default configuration

1. Check config file location
   • Ensure config file is in the correct directory
   • Verify file name is correct
2. Validate JSON syntax
   • Use a JSON validator to check for syntax errors
   • Check for missing commas, brackets, or quotes
   • Use JSON5 validator if using JSON5 features
3. Restart NapCat
   • Configuration changes require restart
   • Close completely before restarting
4. Check file permissions
   • Ensure NapCat can read the config file
   • On Linux: chmod 644 config.json

​

Invalid Configuration Error

• “Invalid configuration” error on startup
• NapCat fails to start

1. Check required fields
   {
     "network": {
       "httpServers": [{
         "name": "http-server",  // Required
         "enable": true,          // Required
         "port": 3000            // Required
       }]
     }
   }
   
2. Verify data types
   • port must be number, not string
   • enable must be boolean, not string
   • Arrays must use [], objects must use {}
3. Check for typos
   • Field names are case-sensitive
   • Use exact field names from documentation

​

Performance Issues

​

High Memory Usage

• NapCat uses excessive RAM
• System becomes slow

1. Limit message history
   • Reduce message cache size if available
   • Clear old logs periodically
2. Disable debug logging
   {
     "debug": false
   }
   
3. Reduce concurrent connections
   • Limit number of WebSocket connections
   • Use fewer network adapters
4. Update to latest version
   • Newer versions may have memory optimizations

​

High CPU Usage

• CPU usage constantly high
• System becomes unresponsive

1. Check heartbeat intervals
   {
     "heartInterval": 60000  // Increase interval (60 seconds)
   }
   
2. Reduce logging verbosity
   • Disable debug mode
   • Reduce log output
3. Check for message loops
   • Ensure bot isn’t responding to its own messages
   • Use reportSelfMessage: false

​

Debugging Tips

​

Enable Debug Logging

{
  "network": {
    "httpServers": [{
      "debug": true  // Enable for each adapter
    }]
  }
}

​

Check Logs

• [OneBot] - OneBot related logs
• [HTTP Server] - HTTP server logs
• [WebSocket] - WebSocket logs
• [Http Client] - Webhook logs

​

Test with Minimal Configuration

{
  "network": {
    "httpServers": [{
      "name": "test",
      "enable": true,
      "port": 3000,
      "host": "127.0.0.1",
      "token": ""
    }]
  }
}

​

Use API Testing Tools

• Postman or Insomnia for HTTP API testing
• wscat for WebSocket testing
  npm install -g wscat
  wscat -c ws://localhost:3001
  

​

Monitor Network Traffic

# Linux - monitor port traffic
sudo tcpdump -i any port 3000

# Check listening ports
netstat -tulpn | grep napcat

​

Getting Help

​

Before Asking for Help

1. Search existing issues - Check GitHub issues for similar problems
2. Read documentation - Review relevant documentation sections
3. Check version - Ensure you’re using the latest version
4. Gather information:
   • NapCat version
   • NTQQ version
   • Operating system
   • Configuration (remove sensitive tokens)
   • Error messages and logs
   • Steps to reproduce

​

Community Support

• NapCat Family Group 1 (1090875633)
• NapCat Family Group 2 (1059714215)
• NapCat Family Group 3 (1085662710)
• NapCat Family Group 4 (1085359803)

​

Reporting Bugs

1. Use a clear, descriptive title
2. Include steps to reproduce
3. Provide expected vs actual behavior
4. Include relevant logs and configuration
5. Specify environment details

​

Next Steps

• Check the FAQ for frequently asked questions
• Review API documentation for API usage
• Join the community for support