​

Toolkit Troubleshooting Guide

​

Authentication Issues

​

OAuth Authentication Problems

​

Error: “invalid_grant”

• Incorrect Client ID or Client Secret
• Mismatched redirect URI
• Expired or revoked credentials
• Clock synchronization issues

1. Verify Credentials
   • Double-check Client ID and Client Secret
   • Ensure no extra spaces or characters
   • Copy credentials directly from the service provider
2. Check Redirect URI
   • Ensure redirect URI matches exactly (including protocol and port)
   • Common format: https://your-domain.com/user/integrations/{service}/oauth/callback
   • Check for trailing slashes or missing paths
3. Regenerate Credentials
   • Create new OAuth credentials in the service provider console
   • Update credentials in Odin Super Admin panel
   • Test authentication again
4. Check System Time
   • Ensure server time is synchronized
   • OAuth tokens are time-sensitive

​

Error: “insufficient_permission”

• Missing required OAuth scopes
• User hasn’t granted necessary permissions
• Admin consent required but not provided

1. Check OAuth Scopes
   • Verify all required scopes are included
   • Compare with toolkit documentation requirements
   • Add missing scopes to OAuth app configuration
2. Grant Admin Consent
   • For enterprise applications, admin consent may be required
   • Contact your organization’s administrator
   • Ensure proper approval workflow is followed
3. Re-authenticate User
   • Have user re-authenticate with updated scopes
   • Clear existing tokens and start fresh
   • Test with a different user account

​

Error: “access_denied”

• User clicked “Deny” during OAuth flow
• App not approved for organization
• Suspicious activity detected

1. User Education
   • Explain why permissions are needed
   • Provide clear instructions for OAuth flow
   • Show benefits of granting access
2. App Approval
   • Ensure app is approved for your organization
   • Contact service provider for app review
   • Use verified app status when possible

​

API Key Issues

​

Error: “invalid_api_key”

• Incorrect API key
• Expired API key
• Key not activated
• Wrong environment (sandbox vs production)

1. Verify API Key
   • Check key is copied correctly
   • Ensure no extra spaces or characters
   • Verify key is for correct service
2. Check Key Status
   • Verify key is active and not expired
   • Check if key has required permissions
   • Ensure key is for correct environment
3. Regenerate Key
   • Create new API key if needed
   • Update key in Odin configuration
   • Test with new key

​

Connection Issues

​

Database Connection Problems

​

Error: “connection_refused”

• Incorrect connection parameters
• Database server not running
• Network connectivity issues
• Firewall blocking connection

1. Verify Connection Parameters
   • Check host, port, database name
   • Verify username and password
   • Ensure correct connection string format
2. Test Network Connectivity
   • Ping database server
   • Check if port is accessible
   • Verify firewall rules
3. Check Database Status
   • Ensure database server is running
   • Check database logs for errors
   • Verify database is accepting connections

​

Error: “authentication_failed”

• Incorrect username or password
• User doesn’t exist
• Insufficient permissions
• Account locked or disabled

1. Verify Credentials
   • Check username and password
   • Test credentials with database client
   • Ensure no special characters causing issues
2. Check User Permissions
   • Verify user has required permissions
   • Check if user can connect from your IP
   • Ensure user is not locked or disabled

​

API Connection Problems

​

Error: “timeout”

• Network connectivity issues
• API server overloaded
• Request too large or complex
• Rate limiting

1. Check Network
   • Test internet connectivity
   • Check if API service is accessible
   • Verify DNS resolution
2. Optimize Requests
   • Reduce request size
   • Simplify complex queries
   • Use pagination for large datasets
3. Handle Rate Limits
   • Implement exponential backoff
   • Reduce request frequency
   • Use batch operations when possible

​

Data Issues

​

File Access Problems

​

Error: “file_not_found”

• Incorrect file path
• File doesn’t exist
• Insufficient permissions
• File moved or deleted

1. Verify File Path
   • Check path is correct and complete
   • Ensure proper path separators
   • Test path with file browser
2. Check Permissions
   • Verify user has read/write access
   • Check file ownership
   • Ensure proper sharing settings
3. File Existence
   • Confirm file exists at specified location
   • Check if file was moved or renamed
   • Verify file is not corrupted

​

Data Format Issues

​

Error: “invalid_format”

• Unexpected data format
• Missing required fields
• Encoding issues
• Corrupted data

1. Validate Data Format
   • Check data structure matches expectations
   • Verify required fields are present
   • Test with sample data
2. Handle Encoding
   • Ensure proper character encoding
   • Use UTF-8 when possible
   • Handle special characters properly
3. Data Cleaning
   • Remove or fix corrupted data
   • Handle missing values
   • Normalize data formats

​

Performance Issues

​

Slow Operations

​

Symptoms**: Toolkit operations are slow

• Large data volumes
• Inefficient queries
• Network latency
• Resource constraints

1. Optimize Queries
   • Use appropriate filters
   • Limit result sets
   • Use efficient data structures
2. Batch Operations
   • Process data in batches
   • Use bulk operations when possible
   • Implement pagination
3. Caching
   • Cache frequently accessed data
   • Use appropriate cache expiration
   • Implement smart cache invalidation

​

Memory Issues

​

Error: “out_of_memory”

• Large datasets
• Memory leaks
• Inefficient algorithms
• Resource limits

1. Optimize Memory Usage
   • Process data in chunks
   • Use streaming when possible
   • Clean up unused variables
2. Algorithm Optimization
   • Use more efficient algorithms
   • Reduce data duplication
   • Implement lazy loading

​

Service-Specific Issues

​

Google Workspace Issues

​

Error: “quota_exceeded”

• Monitor API usage in Google Cloud Console
• Implement rate limiting
• Request quota increase if needed
• Use batch operations

​

Error: “domain_not_verified”

• Verify domain ownership
• Complete domain verification process
• Check admin consent requirements

​

Microsoft 365 Issues

​

Error: “tenant_not_found”

• Verify tenant ID is correct
• Check if tenant exists and is accessible
• Ensure proper Azure AD configuration

​

Error: “app_not_found”

• Verify app registration exists
• Check app ID and tenant ID
• Ensure app is properly configured

​

Salesforce Issues

​

Error: “invalid_session_id”

• Implement token refresh logic
• Handle session expiration gracefully
• Use refresh tokens when available

​

Debugging Tips

​

Enable Debug Logging

1. Check Odin Logs
   • Review application logs for errors
   • Look for authentication failures
   • Check API request/response logs
2. Service Provider Logs
   • Check service provider dashboards
   • Review API usage statistics
   • Look for error patterns

​

Test Connectivity

1. Independent Testing
   • Test OAuth flow outside Odin
   • Verify API keys with service tools
   • Check database connections with clients
2. Network Diagnostics
   • Use ping and telnet for connectivity
   • Check DNS resolution
   • Verify firewall rules

​

Common Debug Commands

# Test network connectivity
ping api.service.com
telnet api.service.com 443

# Check DNS resolution
nslookup api.service.com
dig api.service.com

# Test SSL connectivity
openssl s_client -connect api.service.com:443

​

Getting Help

​

Self-Service Resources

1. Documentation
   • Review toolkit-specific documentation
   • Check service provider documentation
   • Look for API reference guides
2. Community Forums
   • Search for similar issues
   • Post questions with detailed information
   • Share solutions with community

​

Contact Support

1. Error Details
   • Exact error messages
   • Screenshots if applicable
   • Log entries
2. Configuration Information
   • Toolkit being used
   • Setup steps taken
   • Configuration details (without sensitive data)
3. Environment Details
   • Odin version
   • Browser and OS
   • Network environment
4. Steps to Reproduce
   • Detailed steps to reproduce the issue
   • Expected vs actual behavior
   • Frequency of occurrence

​

Support Channels

• Email: support@getodin.ai
• Documentation: This troubleshooting guide
• Community: User forums and discussions