junegunn/fzf · error

unable to put non-printable character

Error message

unable to put non-printable character

What it means

Thrown while parsing a --bind action list containing 'put'. The 'put' action types the bound key's literal character into the prompt, so it is only legal when the key itself is a printable character (putAllowed). Binding 'put' to a non-printable key such as f5, ctrl-a, or tab makes no sense and is rejected.

Source

Thrown at src/options.go:1959

		case "preview-down":
			appendAction(actPreviewDown)
		case "preview-page-up":
			appendAction(actPreviewPageUp)
		case "preview-page-down":
			appendAction(actPreviewPageDown)
		case "preview-half-page-up":
			appendAction(actPreviewHalfPageUp)
		case "preview-half-page-down":
			appendAction(actPreviewHalfPageDown)
		case "enable-search":
			appendAction(actEnableSearch)
		case "disable-search":
			appendAction(actDisableSearch)
		case "put":
			if putAllowed {
				appendAction(actChar)
			} else {
				return nil, errors.New("unable to put non-printable character")
			}
		case "wait":
			appendAction(actWait)
		case "bell":
			appendAction(actBell)
		case "exclude":
			appendAction(actExclude)
		case "exclude-multi":
			appendAction(actExcludeMulti)
		case "bg-cancel":
			appendAction(actBgCancel)
		default:
			t := isExecuteAction(specLower)
			if t == actIgnore {
				if specIndex == 0 && specLower == "" {
					actions = append(prevActions, actions...)
				} else if specLower == "change-multi" {
					appendAction(actChangeMulti)

View on GitHub (pinned to bd4efa277b)

Solutions

1. Bind 'put' only to single printable characters: `--bind 'a:put'`
2. For non-printable keys use an explicit action like 'insert-character' alternatives (e.g. execute(...) or transform) instead of 'put'
3. If you wanted to paste from clipboard, use the clipboard actions (e.g. paste) rather than 'put'

Example fix

# before
fzf --bind 'ctrl-a:put'
# after
fzf --bind 'a:put'

# bash: only single printable chars may carry 'put'
bind_put_ok() {
  # $1 = key; single character and not a control char
  [ "${#1}" -eq 1 ] && [[ "$1" =~ [[:print:]] ]] && ! [[ "$1" =~ [[:cntrl:]] ]]
}
bind_put_ok "$KEY" && fzf --bind "$KEY:put"

When it happens

Trigger: `--bind 'ctrl-a:put'`, `--bind 'f5:put'`, `--bind 'tab:put'` — any 'put' action attached to a key whose event is not printable. putAllowed is false for those keys when parseActionList is called from parseKeymap.

Common situations: Copy-pasting a bind line written for a different key (e.g. changing `--bind 'a:put'` to `--bind 'ctrl-a:put'` without realizing 'put' depends on the key glyph); shell scripts that generate bind entries programmatically for arbitrary keys.

Related errors

• unknown action: ${spec}
• key name required
• bind action not specified: ${keys}
• multiple keys specified
• at least one of 'file' or 'dir' should be specified

AI-assisted analysis of junegunn/fzf@bd4efa277b (2026-08-15). Data as JSON: /api/errors/b51ad9c66f2159f4. Report an issue: GitHub.