Troubleshooting

bindkey '^L' clear-screen

The key sequence (^L in the example) does not match the key sequence being sent to the terminal

Diagnose

You can see the exact sequence a keyboard shortcut sends by pressing CTRL+V and then the keyboard shortcut. For example: CTRL+V, CTRL+L will output ^L (^ represents the Control key).

The command executed (clear-screen in the example) has an error

Diagnose

In that case, post both the key binding and the definition of the command (if exists) like so:

• key binding: bindkey '^[[1;6D'
  will print "^[[1;6D" insert-cycledleft
• command definition: which insert-cycledleft
  will print insert-cycledleft () { ... }

  Notice that sometimes the command is a builtin zle widget and so the which command won't work. If that's the case, just post the key binding and we'll figure it out.

Completions misbehave — including command not found: compdef

Fix 1 · reset the cache

First, try to remove your completion cache with rm ~/.zcompdump*, close and reopen your shells.

Still broken after clearing the cache

Fix 2 · fully reset the completion system

As explained by @dragon788:

compaudit | xargs chmod g-w,o-w
compaudit | xargs chown "$USER"
rm ~/.zcompdump*
exec zsh

Nothing helps — you might have encountered a bug within a particular command's completion

Fix 3 · report it

Open a new issue documenting the issue, and if possible provide a trace of the completion function. You can do that by writing the command you want to complete, then pressing CTRL+X followed by ?.

You're getting weird behavior and can't find the culprit

Last resort · debug mode

Run the following command to enable debug mode:

zsh -xv 2> >(tee ~/omz-debug.log &>/dev/null)

Afterwards, reproduce the behavior (i.e. if it's a particular command, run it), and when you're done, run exit to stop the debugging session. This will create a omz-debug.log file on your home directory, with a trace of every command executed and its output. You can then upload this file when creating an issue.

If you only need to debug the session initialization, you can do so with the command:

zsh -xvic exit &> ~/omz-debug.log