Skip to content

Troubleshooting

"no HIKERAPI_TOKEN configured"

You are using the default hikerapi backend without setting up a token. Either:

insto setup                            # interactive wizard, writes ~/.insto/config.toml
# or
export HIKERAPI_TOKEN=hk_live_...
# or
insto -c info instagram --hiker-token=hk_live_...

Precedence is flag > env > toml.

If you meant to use aiograpi instead, install the optional dependency and run setup again:

pipx inject insto aiograpi                         # existing pipx install
uv tool install --force 'insto[aiograpi]'          # existing uv tool install
insto setup                                        # choose aiograpi

"aiograpi backend requested but the aiograpi package is not installed"

aiograpi is optional. Choosing it in insto setup writes credentials, but it does not mutate the already-installed tool environment. Add the extra:

pipx inject insto aiograpi                         # existing pipx install
pipx install 'insto[aiograpi]'                     # fresh pipx install
uv tool install --force 'insto[aiograpi]'          # uv tool install / reinstall

Then run insto setup, pick aiograpi, and launch insto again.

"balance: pending" in the welcome banner

The startup /sys/balance call hasn't returned yet. By default insto waits up to 2 s for this; on a slow network the banner falls back to "balance: pending" and the actual figure shows up the next time you run /quota.

If it stays "pending":

  • Network blocked — try --proxy http://your-proxy:8080.
  • Token wrong — /health will surface AuthInvalid on the next call.

"schema drift in : missing field "

HikerAPI changed the shape of one of its responses. The mapper refused to silently fill a default — this is a SchemaDrift exception, not a bug in your invocation.

What to do:

  1. /health shows the schema-drift counter for this session.
  2. Open an issue with the command you ran and the failing field name.
  3. Workarounds typically land in the next patch release.

"filesystem does not support xattr; tagging skipped"

Showing once on macOS over an NFS-mounted output directory. insto is trying to set com.apple.metadata:kMDItemUserTags=insto on every downloaded media file so they're greppable in Finder. NFS doesn't carry xattr; the file is downloaded fine, only the tag is skipped.

No action needed.

REPL: typing / doesn't open a popup

The slash popup needs a TTY. If you launched insto with stdin piped (e.g. inside a build script), prompt_toolkit prints Warning: Input is not a terminal (fd=0). and runs without the popup. Use one-shot CLI for scripts:

echo /info instagram | insto              # ← does not open popup
insto -c info instagram                   # ← script-friendly

If you have a TTY but the popup still doesn't show:

  • Make sure your terminal renders 256-color or truecolor; Apple Terminal in 16-color mode won't show the muted help-meta column.
  • If you're on tmux, set -g default-terminal "tmux-256color" is the usual fix.

Disk full mid-/dossier

/dossier checks shutil.disk_usage ≥ 2 GB before starting. If you hit "disk full" during a download anyway, the CDN streamer aborts that file's <pk>.part (no rename), but already-downloaded files stay. MANIFEST.md is written with partial: true. Free space and run /dossier again — it doesn't dedupe, it writes to a new timestamped subdir.

/batch keeps re-running already-processed targets

Resume state for a given input file lives in output/.batch-<sha>.jsonl where the sha hashes the input file's contents. If you tweaked the input list, the sha changes and resume doesn't see prior progress.

To force a clean run regardless of file content:

/batch users.txt info --restart

"sqlite is locked — another insto session running?"

migrate_to_latest() is taking a BEGIN IMMEDIATE lock and another insto process is also starting. Wait for the other process to finish startup, or close it. The retry budget is 100ms / 250ms / 500ms.

If no other insto is running, your ~/.insto/store.db got into a journal_mode=wal state from a previous crash:

sqlite3 ~/.insto/store.db 'PRAGMA wal_checkpoint(TRUNCATE);'

/health shows last_error: AuthInvalid

Your HikerAPI token was rotated or revoked. Run insto setup again to paste a fresh one. The token is only stored in ~/.insto/config.toml (mode 0600); rotation is the right hygiene move after any leak.