Common Issues

Common Issues and Troubleshooting

This guide helps you resolve common problems you might encounter while using ApyGuard.

Table of Contents

• Authentication Issues
• Scan Problems
• API Collection Issues
• Performance Problems
• Integration Issues
• Account and Billing

Authentication Issues

”401 Unauthorized” Errors

Symptoms:

• Scans fail with 401 errors
• Cannot access protected endpoints
• Authentication test fails

Common Causes:

1. Invalid API Key: API key is incorrect or expired
2. Expired Token: OAuth/Bearer token has expired
3. Wrong Header Name: Authentication header name is incorrect
4. Missing Authentication: No authentication configured

Solutions:

1. Verify API Key:
   # Test with curl
   curl -H "X-API-Key: your-api-key" https://your-api.com/endpoint
   
2. Check Token Expiration:
   • Verify token hasn’t expired
   • Refresh OAuth tokens if needed
   • Update Bearer tokens
3. Confirm Header Configuration:
   • Check header name spelling
   • Verify header format (e.g., “Bearer token” vs “token”)
   • Test with Postman or curl
4. Test Authentication Manually:
   • Use Postman to test authentication
   • Verify credentials work outside ApyGuard
   • Check API documentation for requirements

”403 Forbidden” Errors

Symptoms:

• Authentication works but access denied
• Some endpoints work, others don’t
• Permission errors during scans

Common Causes:

1. Insufficient Permissions: Token doesn’t have required scope
2. IP Restrictions: API restricted to specific IP addresses
3. Rate Limiting: Too many requests from your IP
4. User Role Issues: User account lacks necessary permissions

Solutions:

1. Check Token Scope:
   • Verify OAuth token has required permissions
   • Check API key permissions
   • Contact API provider for scope requirements
2. Verify IP Access:
   • Check if API has IP restrictions
   • Add your IP to whitelist if needed
   • Use VPN if required
3. Review Rate Limits:
   • Reduce scan rate in ApyGuard settings
   • Check API provider’s rate limits
   • Schedule scans during off-peak hours

OAuth 2.0 Issues

Symptoms:

• OAuth flow fails
• Token refresh doesn’t work
• Authorization errors

Common Causes:

1. Incorrect OAuth Configuration: Wrong URLs or credentials
2. Redirect URI Mismatch: Callback URL doesn’t match
3. Scope Issues: Missing required permissions
4. Client Configuration: Wrong client ID/secret

Solutions:

1. Verify OAuth Settings:
   Client ID: [your-client-id]
   Client Secret: [your-client-secret]
   Authorization URL: https://api.example.com/oauth/authorize
   Token URL: https://api.example.com/oauth/token
   Redirect URI: https://apyguard.com/oauth/callback
   
2. Check Redirect URI:
   • Ensure redirect URI matches exactly
   • Add redirect URI to OAuth app settings
   • Use HTTPS for production
3. Verify Scope:
   • Check required scopes in API documentation
   • Ensure token has necessary permissions
   • Test scope with OAuth provider

Scan Problems

Scan Failures

Symptoms:

• Scans fail to start
• Scans stop unexpectedly
• Error messages during scanning

Common Causes:

1. Network Issues: Connectivity problems
2. API Unavailability: Target API is down
3. Configuration Errors: Invalid scan settings
4. Resource Limits: Exceeded scan limits

Solutions:

1. Check Network Connectivity:
   # Test API accessibility
   curl -I https://your-api.com/health
   ping your-api.com
   
2. Verify API Status:
   • Check API provider status page
   • Test API endpoints manually
   • Verify API is accessible
3. Review Scan Configuration:
   • Check authentication settings
   • Verify endpoint URLs
   • Review rate limiting settings
4. Check Resource Limits:
   • Verify scan quota not exceeded
   • Check subscription limits
   • Contact support if needed

Slow Scans

Symptoms:

• Scans take much longer than expected
• Progress is very slow
• Timeout errors

Common Causes:

1. High Rate Limiting: Too conservative rate limits
2. Large API: Too many endpoints
3. Slow API Responses: Target API is slow
4. Network Latency: High network latency

Solutions:

1. Optimize Rate Limits:
   • Increase requests per second (if API allows)
   • Reduce concurrent request limits
   • Monitor API response times
2. Reduce Scan Scope:
   • Select fewer endpoints
   • Use Basic scan depth instead of Deep
   • Exclude unnecessary endpoints
3. Improve Network Performance:
   • Use faster internet connection
   • Check for network issues
   • Consider geographic location

False Positives

Symptoms:

• Vulnerabilities reported that aren’t real
• Expected behavior flagged as security issue
• Incorrect risk assessments

Common Causes:

1. Business Logic: Expected application behavior
2. Test Environment: Development/staging differences
3. Custom Logic: Application-specific functionality
4. Scan Configuration: Inappropriate test settings

Solutions:

1. Review Findings Carefully:
   • Understand the reported vulnerability
   • Test manually if needed
   • Check business context
2. Mark False Positives:
   • Mark findings as false positive
   • Add explanatory notes
   • Exclude from future scans
3. Adjust Scan Configuration:
   • Modify test categories
   • Exclude specific endpoints
   • Use custom scan templates

API Collection Issues

Import Failures

Symptoms:

• Cannot import API specification
• Import errors or warnings
• Missing endpoints after import

Common Causes:

1. Invalid File Format: Unsupported or corrupted file
2. Missing Required Fields: Incomplete specification
3. Syntax Errors: YAML/JSON syntax issues
4. Version Compatibility: Unsupported specification version

Solutions:

1. Validate File Format:
   # Validate OpenAPI specification
   npm install -g swagger-cli
   swagger-cli validate your-api.yaml
   
2. Check File Structure:
   • Verify required fields are present
   • Check for syntax errors
   • Ensure proper indentation (YAML)
3. Try Different Formats:
   • Convert between YAML and JSON
   • Use different specification version
   • Export from different tools

Missing Endpoints

Symptoms:

• Some endpoints not imported
• Incomplete API coverage
• Missing authentication endpoints

Common Causes:

1. Specification Issues: Endpoints not in specification
2. Import Filters: Endpoints filtered out
3. Authentication Requirements: Protected endpoints not accessible
4. Version Differences: API version mismatch

Solutions:

1. Check Specification:
   • Verify all endpoints are in specification
   • Check for path conflicts
   • Review endpoint definitions
2. Manual Addition:
   • Add missing endpoints manually
   • Import from different source
   • Update specification file
3. Verify API Version:
   • Check API version in specification
   • Ensure version matches actual API
   • Update specification if needed

Performance Problems

High Resource Usage

Symptoms:

• Slow application performance
• High CPU/memory usage
• Browser becomes unresponsive

Common Causes:

1. Large Scans: Too many concurrent scans
2. Browser Issues: Too many open tabs
3. Network Problems: Slow internet connection
4. System Resources: Insufficient system resources

Solutions:

1. Limit Concurrent Scans:
   • Run one scan at a time
   • Wait for scans to complete
   • Use smaller scan batches
2. Optimize Browser Usage:
   • Close unnecessary tabs
   • Clear browser cache
   • Use incognito mode
3. Check System Resources:
   • Monitor CPU and memory usage
   • Close other applications
   • Restart browser if needed

Slow Dashboard Loading

Symptoms:

• Dashboard takes long to load
• Charts and graphs slow to render
• Timeout errors

Common Causes:

1. Large Data Sets: Too much data to load
2. Network Issues: Slow internet connection
3. Browser Performance: Browser performance issues
4. Server Issues: ApyGuard server problems

Solutions:

1. Optimize Data Loading:
   • Use date filters to limit data
   • Select specific collections
   • Use pagination if available
2. Check Network:
   • Test internet speed
   • Try different network
   • Clear DNS cache
3. Browser Optimization:
   • Update browser to latest version
   • Disable browser extensions
   • Clear browser cache and cookies

Integration Issues

CI/CD Integration Problems

Symptoms:

• GitHub Actions fail
• Webhook notifications don’t work
• Integration errors

Common Causes:

1. Configuration Errors: Wrong webhook URLs or secrets
2. Permission Issues: Insufficient GitHub permissions
3. Network Problems: Firewall or proxy issues
4. API Changes: Integration API changes

Solutions:

1. Verify Configuration:
   • Check webhook URL and secret
   • Verify GitHub repository permissions
   • Test webhook manually
2. Check Permissions:
   • Ensure GitHub app has required permissions
   • Verify repository access
   • Check organization settings
3. Test Integration:
   # Test webhook manually
   curl -X POST -H "Content-Type: application/json" \
        -d '{"test": "data"}' \
        https://your-webhook-url.com
   

Webhook Issues

Symptoms:

• Webhooks not received
• Incorrect webhook data
• Webhook failures

Common Causes:

1. URL Issues: Incorrect webhook URL
2. Authentication: Missing or wrong authentication
3. Format Problems: Incorrect payload format
4. Network Issues: Firewall or proxy blocking

Solutions:

1. Verify Webhook URL:
   • Check URL is correct and accessible
   • Test URL with curl or Postman
   • Ensure HTTPS for production
2. Check Authentication:
   • Verify webhook secret
   • Check authentication headers
   • Test authentication manually
3. Validate Payload:
   • Check payload format
   • Verify required fields
   • Test with sample data

Account and Billing

Login Issues

Symptoms:

• Cannot log in to account
• Password reset doesn’t work
• 2FA problems

Common Causes:

1. Wrong Credentials: Incorrect email/password
2. Account Locked: Too many failed attempts
3. 2FA Issues: Lost 2FA device or codes
4. Email Problems: Email delivery issues

Solutions:

1. Reset Password:
   • Use “Forgot Password” link
   • Check email (including spam)
   • Use strong, unique password
2. 2FA Recovery:
   • Use backup codes if available
   • Contact support for 2FA reset
   • Set up new 2FA device
3. Account Recovery:
   • Contact support with account details
   • Provide proof of ownership
   • Follow account recovery process

Billing Issues

Symptoms:

• Payment failures
• Subscription problems
• Billing errors

Common Causes:

1. Payment Method: Expired or invalid payment method
2. Subscription Limits: Exceeded plan limits
3. Billing Cycle: Billing date issues
4. Currency Problems: Currency conversion issues

Solutions:

1. Update Payment Method:
   • Add new payment method
   • Verify payment method is valid
   • Check billing address
2. Check Subscription:
   • Review current plan
   • Check usage limits
   • Upgrade if needed
3. Contact Billing Support:
   • Email [e-mail]
   • Provide account details
   • Describe the issue clearly

Getting Additional Help

When to Contact Support

Contact ApyGuard support when:

• Critical Issues: Cannot use the platform
• Security Concerns: Potential security problems
• Billing Problems: Payment or subscription issues
• Feature Requests: Missing functionality
• Bug Reports: Platform bugs or errors

How to Contact Support

1. In-App Chat: Use the chat widget in the dashboard
2. Email Support: [e-mail]
3. Billing Support: [e-mail]
4. Emergency Issues: Use in-app chat for immediate assistance

Information to Provide

When contacting support, provide:

• Account Information: Email address
• Issue Description: Clear description of the problem
• Steps to Reproduce: How to reproduce the issue
• Error Messages: Exact error messages
• Screenshots: Visual evidence if helpful
• Browser/OS: Browser and operating system details

Self-Service Resources

Before contacting support:

1. Check Documentation: Review relevant guides
2. Search FAQ: Look for similar issues
3. Community Forum: Check community discussions
4. Status Page: Check ApyGuard status