Fob
Browse the docs

Troubleshooting

fob-zb error messages link straight to the matching section below. For a stack trace, rerun the command with FOB_DEBUG=1.

Invalid code#

Grant code is invalid or already used (they are single-use and short-lived). Generate a fresh one.

Cause: Grant codes expire after the duration you picked (at most 10 minutes) and work exactly once. Running config profiles add a second time with the same code fails.

Fix: Generate a new code on the Self Client's Generate Code tab (steps) and run config profiles add right away.

Invalid client#

client_id / client_secret is invalid, or does not match this data center (region).

Cause: Either a copy-paste error in the ID or secret, or a region mismatch: the client was made in one region's API Console and --region names another.

Fix:

  1. Check which console you used. Its domain matches the region flag in the regions table.
  2. Re-add the profile with the matching --region and a new grant code. Check the ID and secret for stray spaces.

Invalid grant#

Refresh token is invalid or has been revoked. Generate a new grant code and re-add the profile.

Cause: The refresh token no longer works. Common reasons:

  • fob-zb auth logout was run on this profile, or on another profile sharing the same token (details).
  • The Self Client was deleted, or its secret was regenerated, in the API Console.
  • Access was revoked from your Zoho account's connected apps.

Fix: Generate a new grant code and re-add the profile with the same name. Only the flags you pass change:

fob-zb config profiles add myorg --grant-code 1000.zzzzzzzz

If other profiles shared the old token, re-copy them: fob-zb config profiles add other --from myorg --organization-id ….

Token errors#

Zoho token error: <code>.

Cause: Zoho refused the token request for a reason fob-zb doesn't recognise.

Fix: Run fob-zb auth status to see the profile, region and token state, then fob-zb auth refresh to force a new access token. If it keeps failing, open an issue with the error code. Never include your secret or tokens.

No profile selected#

No Zoho Books profile selected. Run `fob-zb getting-started` to connect one (or set FOB_ZB_* env).

Fix: Run fob-zb getting-started. If you have profiles but none is current, run fob-zb config profiles use name. In a worker, set all four required FOB_ZB_* variables. A partial set is ignored on purpose.

Organization not found or not set#

Some calls fail with a Zoho message about the organization when the profile has no organization_id. This happens when your login sees several organizations and none was picked.

Fix:

fob-zb organizations list
fob-zb config profiles add myorg --organization-id 8927xxxxxx

Not authorized for an operation#

Zoho returns an authorization error when the grant code's scopes don't cover the command, for example a write on a read-only profile. It also happens when your Zoho user's role in that organization lacks the permission.

Fix: Use a profile with broader scopes, or ask the organization admin to change your role.

The command isn't found#

If fob-zb: command not found appears after installing, see Install the CLI.