Skip to main content

​
Overview

IQKeyboardManager includes built-in debug logging to help you understand what’s happening behind the scenes and troubleshoot issues. This guide covers enabling debug logs, common issues, and how to resolve them.

​
Enable Debug Logging

Enable debug logging in your AppDelegate to see detailed information about keyboard events:
AppDelegate.swift
import IQKeyboardManagerSwift

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    IQKeyboardManager.shared.isEnabled = true
    
    // Enable debug logging
    IQKeyboardManager.shared.isDebuggingEnabled = true
    
    return true
}
Debug logging should only be enabled during development. Disable it in production builds to avoid performance impact and log clutter.

​
Debug Log Output

When enabled, you’ll see detailed logs in the Xcode console:
Console Output
IQKeyboardManager| Enabled
IQKeyboardManager| keyboardWillShow
IQKeyboardManager|    rootController: <UINavigationController>
IQKeyboardManager|    textFieldView: <UITextField: 0x7f8b1c507c00>
IQKeyboardManager|    adjustingHeight: 216.0
IQKeyboardManager| keyboardDidShow
IQKeyboardManager| keyboardWillHide
IQKeyboardManager| restoring previous position
IQKeyboardManager| keyboardDidHide

​
Log Structure

Logs use indentation to show nested operations: 
IQKeyboardManager|       Top-level event
IQKeyboardManager|    |  Nested operation
IQKeyboardManager|    |  |  Deeper nested operation

​
Enable Toolbar Debugging

Enable separate debugging for toolbar operations:
AppDelegate.swift
IQKeyboardManager.shared.enableAutoToolbar = true
IQKeyboardManager.shared.enableToolbarDebugging = true
You’ll see toolbar-specific logs:
Console Output
IQKeyboardToolbarManager| Toolbar added to <UITextField>
IQKeyboardToolbarManager| Previous button: enabled
IQKeyboardToolbarManager| Next button: enabled
IQKeyboardToolbarManager| Done button: visible

​
Conditional Debugging

Enable debugging only in debug builds:
AppDelegate.swift
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    IQKeyboardManager.shared.isEnabled = true
    
    #if DEBUG
    IQKeyboardManager.shared.isDebuggingEnabled = true
    IQKeyboardManager.shared.enableToolbarDebugging = true
    #endif
    
    return true
}

​
Common Issues and Solutions

​
Keyboard Not Adjusting

Symptom: Keyboard covers text fieldsSolution:
IQKeyboardManager.shared.isEnabled = true
Debug Check: Enable logging and look for “Enabled” message at app launch.
Symptom: Works in some view controllers but not othersSolution: Check if the view controller is in the disabled list:
// Remove from disabled list
IQKeyboardManager.shared.disabledDistanceHandlingClasses = 
    IQKeyboardManager.shared.disabledDistanceHandlingClasses.filter { 
        $0 != MyViewController.self 
    }
Debug Check: Look for logs showing the view controller being skipped.
Symptom: Specific text field not adjustingSolution:
textField.iq.enableMode = .default // or .enabled
Debug Check: Add a breakpoint and check the field’s enableMode property.
Symptom: Text fields in custom containers not detectedSolution:
IQKeyboardManager.shared.deepResponderAllowedContainerClasses.append(
    CustomContainerView.self
)

​
Toolbar Not Appearing

Solution:
IQKeyboardManager.shared.enableAutoToolbar = true
Solution:
IQKeyboardManager.shared.disabledToolbarClasses = 
    IQKeyboardManager.shared.disabledToolbarClasses.filter { 
        $0 != MyViewController.self 
    }
Symptom: You’ve set a custom inputAccessoryViewExplanation: Custom input accessory views override the automatic toolbar.Solution: Remove custom inputAccessoryView or integrate it with IQKeyboardToolbarManager.

​
Tap-to-Dismiss Not Working

Solution:
IQKeyboardManager.shared.resignOnTouchOutside = true
Solution:
IQKeyboardManager.shared.disabledTouchResignedClasses = 
    IQKeyboardManager.shared.disabledTouchResignedClasses.filter { 
        $0 != MyViewController.self 
    }
Solution:
// Make your gesture wait for resign gesture to fail
myGesture.require(toFail: IQKeyboardManager.shared.resignGesture)

​
Performance Issues

Cause: Complex view hierarchy or Auto Layout constraintsSolution:
// Optimize Auto Layout
// Reduce constraint conflicts
// Simplify view hierarchy

// Or disable layout forcing:
IQKeyboardManager.shared.layoutIfNeededOnUpdate = false
Cause: Debug logging enabled in release buildsSolution:
#if DEBUG
IQKeyboardManager.shared.isDebuggingEnabled = true
#endif

​
Manual Management Tweaks

For cases where automatic behavior doesn’t work, you can manually control IQKeyboardManager:

​
Temporarily Disable

ViewController.swift
class SpecialViewController: UIViewController {
    
    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        
        // Temporarily disable
        IQKeyboardManager.shared.isEnabled = false
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        
        // Re-enable
        IQKeyboardManager.shared.isEnabled = true
    }
}

​
Manual Position Adjustment

ViewController.swift
class CustomLayoutViewController: UIViewController {
    
    func updateViewLayout() {
        // Make layout changes
        updateConstraints()
        view.layoutIfNeeded()
        
        // Notify IQKeyboardManager
        IQKeyboardManager.shared.reloadLayoutIfNeeded()
    }
}

​
Custom Distance Calculation

ViewController.swift
class ComplexFormViewController: UIViewController {
    
    @IBOutlet weak var scrollView: UIScrollView!
    @IBOutlet weak var contentView: UIView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Adjust distance based on content
        let contentHeight = contentView.bounds.height
        let scrollHeight = scrollView.bounds.height
        
        if contentHeight > scrollHeight {
            IQKeyboardManager.shared.keyboardDistance = 30.0
        } else {
            IQKeyboardManager.shared.keyboardDistance = 10.0
        }
    }
}

​
Known Issues

For a comprehensive list of known issues and workarounds, see:
The library documentation includes detailed information about edge cases and platform-specific issues.

​
Common Warnings

You may see these warnings in the console:

​
Negative Distance Warning

IQKeyboardManager| ⚠️ keyboardDistance shouldn't be negative.
Solution: Ensure keyboardDistance is >= 0 
IQKeyboardManager.shared.keyboardDistance = max(0, calculatedDistance)

​
Refuses to Resign Warning

IQKeyboardManager| Warning: Refuses to resign first responder: <UITextField>
Cause: The text field’s delegate returned false from textFieldShouldEndEditing(_:) Solution: Check your delegate implementation: 
func textFieldShouldEndEditing(_ textField: UITextField) -> Bool {
    // Validate and allow resignation
    return true
}

​
Debugging Checklist

When troubleshooting, go through this checklist:
1

Enable debug logging

IQKeyboardManager.shared.isDebuggingEnabled = true
2

Check if IQKeyboardManager is enabled

Look for “Enabled” message in console
3

Verify view controller not in disabled list

print(IQKeyboardManager.shared.disabledDistanceHandlingClasses)
4

Check text field enable mode

print(textField.iq.enableMode)
5

Review console logs for errors

Look for warnings or error messages
6

Test with minimal configuration

Temporarily remove custom configuration to isolate the issue
7

Check for gesture conflicts

Disable custom gestures temporarily

​
Getting Help

If you’re still experiencing issues:
  1. Check the GitHub Issues: IQKeyboardManager Issues
  2. Review the Wiki: IQKeyboardManager Wiki
  3. Create a minimal reproducible example
  4. Include debug logs when reporting issues
  5. Specify your environment:
    • iOS version
    • Xcode version
    • IQKeyboardManager version
    • Swift version

​
Debug Configuration Example

Here’s a complete debug configuration:
AppDelegate.swift
import UIKit
import IQKeyboardManagerSwift

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        configureKeyboardManager()
        return true
    }
    
    func configureKeyboardManager() {
        let manager = IQKeyboardManager.shared
        
        // Core setup
        manager.isEnabled = true
        manager.keyboardDistance = 10.0
        
        #if DEBUG
        // Debug logging
        manager.isDebuggingEnabled = true
        manager.enableToolbarDebugging = true
        
        // Print configuration
        printDebugConfiguration()
        #endif
    }
    
    func printDebugConfiguration() {
        let manager = IQKeyboardManager.shared
        
        print("\n=== IQKeyboardManager Debug Configuration ===")
        print("Enabled: \(manager.isEnabled)")
        print("Debugging: \(manager.isDebuggingEnabled)")
        print("Keyboard Distance: \(manager.keyboardDistance)")
        print("Resign on Touch: \(manager.resignOnTouchOutside)")
        print("Auto Toolbar: \(manager.enableAutoToolbar)")
        print("Disabled Classes: \(manager.disabledDistanceHandlingClasses)")
        print("Enabled Classes: \(manager.enabledDistanceHandlingClasses)")
        print("=========================================\n")
    }
}

​
Best Practices

Turn on debug logging when you first integrate IQKeyboardManager to understand its behavior.
Always disable debug logging in production builds using #if DEBUG conditionals.
Start with minimal configuration and only add customization as needed.
Add comments explaining why you’ve disabled or configured specific settings.
Test your forms on different devices, orientations, and iOS versions.

​
Next Steps

Basic Setup

Get started with IQKeyboardManager

Advanced Configuration

Fine-tune keyboard behavior

API Reference

Complete API documentation

GitHub Issues

Report issues or search for solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us