Common Errors

Address Details users may encounter various errors during installation, configuration, and daily operation. This guide provides comprehensive troubleshooting information for the most frequently reported issues.

Installation and Setup Errors

App Installation Failures

1. Error: "App cannot be installed due to missing dependencies"

Cause: Q-Team App Authenticator or Drag & Drop extensions not installed

Solution: - Install Q-Team App Authenticator first - Install Drag & Drop extension - Retry Address Details installation

Prevention: Always check dependency requirements before installation

1. Error: "Extension package is not compatible with this version"

Cause: Address Details version incompatible with Business Central version

Solution: - Check Business Central version compatibility - Contact Q-Team Solutions for compatible app version - Upgrade Business Central if necessary

Verification: Review app.json requirements against BC version

1. Error: "Insufficient permissions to install extension"

Cause: User lacks System Administrator privileges

Solution: - Request System Administrator permissions - Have administrator perform installation - Verify user is in appropriate security groups

Note: Extension installation always requires elevated privileges

License and Registration Errors

1. Error: "License validation failed"

Cause: Invalid or expired Address Details license

Solution: - Verify license is current and valid - Contact Q-Team Solutions for license renewal - Check Q-Team App Authenticator registration

Diagnosis: Check license expiration date and status

1. Error: "App registration with authenticator failed"

Cause: Q-Team App Authenticator not properly configured

Solution: - Ensure Q-Team App Authenticator is installed and activated - Verify authenticator configuration - Retry registration process - Contact Q-Team Solutions support if issues persist

Troubleshooting: Check authenticator logs for detailed error information

Configuration Errors

API Configuration Issues

1. Error: "BAG API authentication failed"

Cause: Invalid API credentials or expired subscription

Solution: - Verify BAG API key and credentials - Check subscription status with Kadaster - Ensure correct API endpoint URLs - Test credentials using BAG API documentation

Testing: Use curl or Postman to verify API access independently

1. Error: "Google Maps API key invalid"

Cause: Incorrect API key or insufficient permissions

Solution: - Verify API key from Google Cloud Platform - Check API key restrictions and permissions - Ensure required APIs are enabled (Maps JavaScript, Geocoding) - Verify billing is set up for Google Cloud project

Common Issue: API key restrictions may block BC domain

1. Error: "Connection timeout during API setup test"

Cause: Network connectivity issues or firewall restrictions

Solution: - Check network connectivity to API endpoints - Verify firewall rules allow HTTPS traffic - Test connectivity from server/user machine - Consider proxy or corporate network restrictions

Testing: Use telnet or ping to test basic connectivity

Permission and Access Errors

1. Error: "User does not have permission to access Address Details"

Cause: User lacks appropriate permission sets

Solution: - Assign QTEAM AD ESSENTIALS or QTEAM AD PREMIUM permission set - Verify user license and entitlement - Check role-based access configuration

Verification: Review User Permission Sets page

1. Error: "Access denied to address validation function"

Cause: Limited license level or permission restrictions

Solution: - Verify user has appropriate license tier (Essential/Premium) - Check feature-specific permissions - Review entitlement configuration

Note: Some features require Premium licensing

Runtime and Operational Errors

Address Validation Errors

1. Error: "Address not found in BAG registry"

Cause: Address doesn't exist or incorrect format

Solution: - Verify address exists and is correctly formatted - Check postal code format (1234AB) - Try alternative search criteria - Use broader search parameters

Note: New addresses may not be immediately available in BAG

1. Error: "Geocoding failed for address"

Cause: Google Maps unable to locate address or API quota exceeded

Solution: - Verify address format and completeness - Check Google Maps API quota and usage - Try alternative address formats - Ensure Google Maps API key is valid

Monitoring: Check Google Cloud Console for API usage statistics

1. Error: "Validation confidence score too low"

Cause: Address information insufficient for confident validation

Solution: - Require more complete address information - Use manual validation override if appropriate - Adjust confidence threshold settings - Consider alternative validation sources

Configuration: Review confidence score requirements in setup

Data Import and Export Errors

1. Error: "Import file format not supported"

Cause: File format incompatible with Address Details

Solution: - Verify file format (CSV, Excel, XML) - Check file encoding (UTF-8 recommended) - Validate file structure and headers - Use provided import templates

Support: Download sample import files from Q-Team Solutions

1. Error: "Data validation failed during import"

Cause: Import data doesn't meet validation requirements

Solution: - Review data validation rules - Check required fields and formats - Validate postal codes and address components - Use data preview to identify issues

Best Practice: Validate small samples before full import

1. Error: "Export operation failed"

Cause: Insufficient permissions or system resources

Solution: - Verify export permissions - Check available disk space - Reduce export data volume if necessary - Try during low-usage periods

Alternative: Use filtered exports for large datasets

Performance and System Errors

Performance Issues

1. Error: "Address lookup operation timeout"

Cause: Slow API response or network issues

Solution: - Check network connectivity and speed - Verify API service availability - Increase timeout values if appropriate - Try during off-peak hours

Monitoring: Monitor API response times and availability

1. Error: "System performance degraded during bulk operations"

Cause: Large data operations overwhelming system resources

Solution: - Process data in smaller batches - Schedule operations during off-peak hours - Increase available system resources - Optimize database performance

Best Practice: Use background processing for large operations

Memory and Resource Errors

1. Error: "Out of memory during data processing"

Cause: Insufficient memory for large operations

Solution: - Reduce batch sizes for processing - Process data incrementally - Increase available memory if possible - Close unnecessary applications

Monitoring: Monitor memory usage during operations

1. Error: "Database connection timeout"

Cause: Database overload or connectivity issues

Solution: - Check database server status and performance - Verify connection string and credentials - Reduce concurrent operations - Contact system administrator for database issues

Escalation: Database issues may require IT support

Integration and Connectivity Errors

Power Automate Integration Errors

1. Error: "Webhook delivery failed"

Cause: Power Automate flow not accessible or incorrect configuration

Solution: - Verify webhook URL is correct and accessible - Check Power Automate flow is active - Verify authentication credentials - Test webhook manually

Testing: Use webhook testing tools to verify connectivity

1. Error: "Flow trigger authentication failed"

Cause: Invalid API key or authentication method

Solution: - Verify API key configuration - Check authentication method settings - Update credentials if expired - Test authentication independently

Documentation: Review Power Automate authentication requirements

External System Integration Errors

1. Error: "HTTP 401 Unauthorized when calling external API"

Cause: Authentication credentials invalid or expired

Solution: - Refresh API tokens and credentials - Verify authentication method - Check API key permissions and restrictions - Update stored credentials

Maintenance: Implement automatic credential refresh where possible

1. Error: "HTTP 429 Too Many Requests"

Cause: API rate limiting exceeded

Solution: - Reduce API call frequency - Implement request queuing and throttling - Check API quota and usage limits - Consider upgrading API subscription

Optimization: Implement intelligent caching to reduce API calls

Error Prevention and Best Practices

Proactive Monitoring

1. Regular Health Checks
   • Monitor API connectivity and response times
   • Check license and subscription status
   • Verify system performance metrics
   • Review error logs for patterns
2. Preventive Maintenance
   • Regular credential rotation and updates
   • Monitor API quota usage and trends
   • Keep system and extensions updated
   • Regular backup and recovery testing

Error Reporting and Escalation

1. When to Contact Support
   • Errors persist after following troubleshooting steps
   • System-wide failures affecting multiple users
   • Data corruption or integrity issues
   • License or billing related problems
2. Information to Provide
   • Exact error messages and screenshots
   • Steps to reproduce the issue
   • System environment and version information
   • Recent changes or updates made
3. Support Channels
   • Q-Team Solutions support portal
   • Email support with detailed error information
   • Emergency contact for critical issues
   • Community forums for general questions

Diagnostic Tools and Utilities

1. Built-in Diagnostics
   • Address Details setup test functions
   • API connectivity tests
   • License validation checks
   • Performance monitoring tools
2. External Verification
   • BAG API testing tools
   • Google Maps API testing utilities
   • Network connectivity testing
   • Database performance monitoring

By following this troubleshooting guide and implementing preventive measures, most common Address Details errors can be resolved quickly and efficiently, ensuring optimal system performance and user experience.