HubSpot CLI troubleshooting
Fix a refused key, a missing scope, a spent daily API allowance or a refused write in HubSpot.
Get hubspot working again from the message it shows. A key that was revoked, a scope left out and a daily allowance
spent each have their own message and their own fix.
Find your symptom in the table and run the check beside it. Your agent can do the same: each error names its reason,
such as session.expired, so it knows what happened. Start with hubspot doctor, which shows what is set up and
needs no network.
On this page:
Symptoms and what to do
| Symptom | What to do |
|---|---|
| Not sure what is set up | Run hubspot doctor. It reads no keyring and uses no network. |
hubspot is not found | Open a new terminal, and check that npm's global folder is on PATH. Another tool may own the word hubspot, such as HubSpot's own Agent CLI: run wcat-hubspot instead. |
| "name a profile" | Put the profile first, as in hubspot work config show, or set WCHUBSPOT_PROFILE. |
| The settings file does not read | doctor lists every problem in the file under config.issues. Run the config unset each one gives, or fix the file by hand. |
doctor lists files.problems | Other users of the computer can read config.json or enter its folder. Run each chmod that doctor prints after "to make it private:". doctor never changes a file mode itself. |
"HubSpot refused the token" (session.expired) | The key was deleted, rotated or mistyped. Make a new one and run hubspot work session start again, as install and connect shows. |
"the token lacks the … scope" (hubspot.scope-missing) | Add the scope the error names to the key in HubSpot. The key keeps working, no new sign-in needed. |
WCHUBSPOT_TOKEN needs WCHUBSPOT_ACCOUNT (account.id-missing) | Set WCHUBSPOT_ACCOUNT to the account's id beside the token. hubspot work session status --check with the token alone prints it as account. |
WCHUBSPOT_ACCOUNT names account …, but the token belongs to account … (account.mismatch) | The id is another account's. Set WCHUBSPOT_ACCOUNT to the id the error names. Nothing was written. |
run hubspot <profile> sync once with WCHUBSPOT_TOKEN first (account.unchecked) | A command that reads only the local copy with WCHUBSPOT_TOKEN needs a checked one first. Run hubspot work sync. |
"already signs in to HubSpot account" (session.duplicate) | Another profile reads that account. Use that profile, or end its session first. |
"spent its daily API allowance" (hubspot.daily-limit) | Every app on the account shares one daily allowance. It comes back at midnight in the account's time zone, and the error says in how many hours. api with WCHUBSPOT_TOKEN does not know the time zone: its error says to try again after a time in UTC, the earliest the allowance can be back. |
owner:me finds nothing | A key names no user. Take the owner's id from hubspot work users list and filter by it, such as owner:51234567. |
| A write is refused | The profile's permissions or WCHUBSPOT_READ_ONLY stop it, as permissions shows. |
Asking for help
Keep the error code and the profile name. hubspot doctor reports create writes a problem report to a file and says
where to send it. Open an issue in the hubspot-cli repository.
Never paste a key, a password or private content into a support request.