Reference

Troubleshooting

Resolve setup, connection, and operation errors.

The shell cannot find finoctl

Check the Node.js version and use the installer’s bin directory in the same environment that runs the CLI.

Terminal

export PATH="$HOME/.local/bin:$PATH"
node --version
finoctl --version

If you used a custom installation root, add its bin directory instead. Use Installation for verification and upgrade steps.

Browser approval does not complete

Symptom	What to check
`BROWSER_LOGIN_UNAVAILABLE`	Verify your version is 0.3.0 or newer and run `finoctl wholesale login --browser` against the regular wholesale site.
Expired or denied request	Check the account and connection name, then generate a fresh request when ready to approve.
`ALREADY_SIGNED_IN`	Use `finoctl wholesale status` to check the existing session. Sign out only if you want to replace that connection.
`UNSAFE_SESSION_STORAGE`	Check ownership and use a private directory with no symlinks. Keep the same directory in each new process.
`SESSION_CLEANUP_UNCONFIRMED`	Keep the existing credential private and retry status or logout when connected.
Product read returns `403`	Check the account’s commerce permissions after confirming authenticated status.

A write times out or conflicts

Keep the original preview, checksum, and operation ID. Read the exact product or order and any available receipt before deciding what to retry. For a stale revision, prepare a fresh preview after inspecting the current state.

Inventory or MCP setup fails

Run finoctl --json doctor. Check the project configuration and Wrangler access for live reads. Use Inventory MCP to verify the local integration with fixture data. For website login status, use finoctl wholesale status.

Ask for help

Send Gallo Fino Support the CLI version, the command you ran with private fields removed, and the error code or diagnostic ID.