How can I debug a user LaunchAgent that doesn't seem to start or load with launchctl?

I had this too, and I think I have a solution.

I read through the launchctl man pages and saw that load and start are now considered legacy subcommands.

Subcommands from the previous implementation of launchd are generally available, though some may be unimplemented.

I think the old behaviour can be achieved by the following two commands:

# Enable this plist
launchctl enable service-target

# Run this plist now
launchctl kickstart service-target

The service-target that worked for me was in the form gui/$UID/myPlistFilename

The plist filename didn't include the .plist on the end.

So, for the file at ~/Library/LaunchAgents/setUserKeyMapping.plist I ran:

launchctl enable gui/$UID/setUserKeyMapping
launchctl kickstart gui/$UID/setUserKeyMapping

If you pass -kp to the kickstart action, it will kill any running instance and restart it, then print out the PID of the new instance.

launchctl kickstart -kp gui/$UID/setUserKeyMapping

In my case, I had this (misleading) Load failed: 5: Input/output error because the service was loaded already. A launchctl unload ~/Library/LaunchAgents/... solved this.