Debugging

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 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

IQKeyboardManager not enabled

Symptom: Keyboard covers text fieldsSolution:

IQKeyboardManager.shared.isEnabled = true

Debug Check: Enable logging and look for “Enabled” message at app launch.

View controller is disabled

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.

Text field has enableMode = .disabled

Symptom: Specific text field not adjustingSolution:

textField.iq.enableMode = .default // or .enabled

Debug Check: Add a breakpoint and check the field’s enableMode property.

Custom container view

Symptom: Text fields in custom containers not detectedSolution:

IQKeyboardManager.shared.deepResponderAllowedContainerClasses.append(
    CustomContainerView.self
)

View controller in disabled list

Solution:

IQKeyboardManager.shared.disabledToolbarClasses = 
    IQKeyboardManager.shared.disabledToolbarClasses.filter { 
        $0 != MyViewController.self 
    }

Custom inputAccessoryView

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

Feature not enabled

Solution:

IQKeyboardManager.shared.resignOnTouchOutside = true

View controller disabled

Solution:

IQKeyboardManager.shared.disabledTouchResignedClasses = 
    IQKeyboardManager.shared.disabledTouchResignedClasses.filter { 
        $0 != MyViewController.self 
    }

Gesture conflict

Solution:

// Make your gesture wait for resign gesture to fail
myGesture.require(toFail: IQKeyboardManager.shared.resignGesture)

Performance Issues

Slow keyboard animation

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

Debug logging in production

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:

Enable debug logging

IQKeyboardManager.shared.isDebuggingEnabled = true

Check if IQKeyboardManager is enabled

Look for “Enabled” message in console

Verify view controller not in disabled list

print(IQKeyboardManager.shared.disabledDistanceHandlingClasses)

Check text field enable mode

print(textField.iq.enableMode)

Review console logs for errors

Look for warnings or error messages

Test with minimal configuration

Temporarily remove custom configuration to isolate the issue

Check for gesture conflicts

Disable custom gestures temporarily

Getting Help

If you’re still experiencing issues:

Check the GitHub Issues: IQKeyboardManager Issues
Review the Wiki: IQKeyboardManager Wiki
Create a minimal reproducible example
Include debug logs when reporting issues
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

Enable logging early in development

Turn on debug logging when you first integrate IQKeyboardManager to understand its behavior.

Disable in production

Always disable debug logging in production builds using #if DEBUG conditionals.

Keep configuration simple

Start with minimal configuration and only add customization as needed.

Document custom behavior

Add comments explaining why you’ve disabled or configured specific settings.

Test thoroughly

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

Get Started

Core Concepts

Guides

Migration

Overview

Enable Debug Logging

Debug Log Output

Log Structure

Conditional Debugging

Common Issues and Solutions

Keyboard Not Adjusting

Tap-to-Dismiss Not Working

Performance Issues

Manual Management Tweaks

Temporarily Disable

Manual Position Adjustment

Custom Distance Calculation

Known Issues

Common Warnings

Negative Distance Warning

Refuses to Resign Warning

Debugging Checklist

Getting Help

Debug Configuration Example

Best Practices

Next Steps

Basic Setup

Advanced Configuration

API Reference

GitHub Issues

​Overview

​Enable Debug Logging

​Debug Log Output

​Log Structure

​Enable Toolbar Debugging

​Conditional Debugging

​Common Issues and Solutions

​Keyboard Not Adjusting

​Toolbar Not Appearing

​Tap-to-Dismiss Not Working

​Performance Issues

​Manual Management Tweaks

​Temporarily Disable

​Manual Position Adjustment

​Custom Distance Calculation

​Known Issues

​Common Warnings

​Negative Distance Warning

​Refuses to Resign Warning

​Debugging Checklist

​Getting Help

​Debug Configuration Example

​Best Practices

​Next Steps

Basic Setup

Advanced Configuration

API Reference

GitHub Issues

Overview

Enable Debug Logging

Debug Log Output

Log Structure

Enable Toolbar Debugging

Conditional Debugging

Common Issues and Solutions

Keyboard Not Adjusting

Toolbar Not Appearing

Tap-to-Dismiss Not Working

Performance Issues

Manual Management Tweaks

Temporarily Disable

Manual Position Adjustment

Custom Distance Calculation

Known Issues

Common Warnings

Negative Distance Warning

Refuses to Resign Warning

Debugging Checklist

Getting Help

Debug Configuration Example

Best Practices

Next Steps