Troubleshooting

Debug logging 

jiq --debug data.json
# or
JIQ_DEBUG=1 jiq data.json

Logs to /tmp/jiq-debug.log (file only, never stdout/stderr).

Reading query errors

When a query fails, press Ctrl+E to open the error overlay. jiq rewrites jq’s raw stderr into a plain-language explanation plus a fix hint — see Decode an error. Unrecognized messages are shown verbatim, so no detail is lost.

This works with jq 1.6 and newer. Older jq releases (1.5 and earlier) phrase errors too differently to normalize reliably and aren’t supported.

Filing a bug

Open a GitHub issue with:

  1. /tmp/jiq-debug.log.
  2. jiq --version.
  3. OS + terminal emulator.
  4. Steps to reproduce.

Known limitations

  • Autocomplete mid-query: editing in the middle of a query falls back to root-level suggestions. Work at the end of the path.
  • Syntax highlighting: keyword-based only, no scope analysis. Use the error overlay (Ctrl+E) for the full jq error.

  • Non-ASCII keys: jq’s .field shorthand is ASCII-only. Use bracket notation for CJK, emoji, hyphens, spaces, digit-starts:

    .["名前"]   ✓ bracket notation (what autocomplete emits)
."名前"     ✓ quoted-dot
.名前        ✗ jq syntax error
  • Clipboard over SSH: OSC 52 read works on modern terminals (Ghostty, kitty, WezTerm, foot) for content copied inside the session. Host-workstation copies don’t round-trip.