Controller not detected

Start here

Start with a wired controller and a direct USB connection.
Try another USB port and a known data-capable cable.
Use a keyboard to inspect controller setup and see whether the device is listed.
If wired input works but Bluetooth does not, investigate pairing separately.

What usually causes this?

Cable, power, connection mode or missing input-device support.

Advanced explanation

Input-device detection happens before button mapping. A remap cannot fix a device the OS cannot see.

Still stuck?

Record what changed after each check. Include your exact board, image, emulator and error when asking for help. These are diagnostic starting points, not guaranteed fixes for every OS.

Controller Configuration: detailed upstream reference →

Reference: RetroPie Controller Configuration documentation. Original companion checklist; historical upstream guidance needs OS-specific review.