Troubleshoot the CLI

Each problem below has the symptom, the cause, and the fix.

Before you start

Run these commands to see your CLI version, account, and profiles:

sitegpt --version
sitegpt whoami
sitegpt profiles list

Add --json to a failing command to see the full error. With --json, errors show a code, a message, and sometimes a hint and details. Add --debug to print request tracing to stderr.

`PROFILE_NOT_CONFIGURED`

Symptom: A command fails with PROFILE_NOT_CONFIGURED. Cause: The CLI has no token. No saved profile exists with that name, and SITEGPT_API_TOKEN is not set. Fix:

If you have an account, run sitegpt login. See Install the CLI and log in.
If you use --profile or SITEGPT_PROFILE, check the name with sitegpt profiles list.
If you do not have an account, this error is expected. Run sitegpt onboarding start <website-url>. It needs no login. See Agent-first onboarding.

`PLAN_UPGRADE_REQUIRED`

Symptom: Commands fail with 403 and PLAN_UPGRADE_REQUIRED. Or, during sitegpt login, the browser page says “API access needs the Growth plan or above.” It shows no Approve or Deny button. Cause: The CLI needs the Growth plan or above. Your account is on a lower plan, or it was downgraded. Fix: Upgrade your plan. See Manage your plan and billing. The login request stays pending, so you can approve it after the upgrade if the code has not expired. Otherwise, run sitegpt login again.

`HIPAA_AI_ASSISTANTS_DISABLED`

Symptom: For a chatbot in a HIPAA workspace, conversation or lead commands fail with 403 and HIPAA_AI_ASSISTANTS_DISABLED. The message tells you to update the CLI to version 0.6.0 or later. Cause: SiteGPT blocks conversation and lead content for AI assistants in HIPAA workspaces. A CLI older than 0.6.0 does not identify itself, so SiteGPT cannot tell a terminal command from the local MCP server. When you signed in with sitegpt login, SiteGPT blocks these requests. Fix: Upgrade the CLI to 0.6.0 or later. See Upgrade the CLI. The local MCP server (sitegpt mcp) stays blocked after the upgrade. See HIPAA.

`DEVICE_LOGIN_EXPIRED`

Symptom: sitegpt login stops with DEVICE_LOGIN_EXPIRED. Cause: You did not approve the request in the browser before the code expired. Fix: Run sitegpt login again. Open the new URL and select Approve right away. Symptom: sitegpt login fails with OPTIONS_CONFLICT. Cause: You used options that do not work together. --full-access and --scope conflict. --token conflicts with every device login option. Fix: Remove one of the options. See Option rules.

The CLI calls the wrong SiteGPT URL

Symptom: Commands reach a local or test server, or fail with NON_JSON_RESPONSE. Cause: SITEGPT_API_BASE is set, or the active profile saved another API base URL. Fix:

Check the API base of the active profile:
sitegpt profiles show

Check the environment:

echo $SITEGPT_API_BASE
echo $SITEGPT_PROFILE
echo $SITEGPT_API_TOKEN

Remove variables that point to the wrong place:

unset SITEGPT_API_BASE
unset SITEGPT_PROFILE
unset SITEGPT_API_TOKEN

If the profile has the wrong URL, log in again with the production URL:
sitegpt login --profile default --api-base https://sitegpt.ai
Run sitegpt whoami again.

`NON_JSON_RESPONSE`

Symptom: A command fails with NON_JSON_RESPONSE. Older CLI versions show Unexpected token '<' ... is not valid JSON instead. Cause: The CLI expected JSON from the API but got something else, often an HTML page. Common causes:

SITEGPT_API_BASE or the profile points to the wrong host.
The CLI version is old.

Fix: Follow The CLI calls the wrong SiteGPT URL. Then upgrade the CLI:

npm install -g @sitegpt/cli@latest

`TOKEN_SCOPE_NOT_ALLOWED` or `TOKEN_SCOPE_NOT_VALID`

Symptom: A command fails with one of these codes. Cause:

TOKEN_SCOPE_NOT_ALLOWED: the token does not have a scope that the command needs. With --json, details.requiredScopes lists the scopes that the command needs.
TOKEN_SCOPE_NOT_VALID: a --scope value is not a real scope name.

Fix:

Check the scope names on Authentication.

sitegpt login \
  --profile knowledge-agent \
  --scope account:read \
  --scope chatbots:read \
  --scope knowledge:read \
  --scope knowledge:write

If the token is limited to some chatbots, check that the chatbot is in the list:
sitegpt chatbots list --profile knowledge-agent

A token cannot do more than your dashboard role allows. If your role cannot access a chatbot or action, no token you create can.

`UNKNOWN_COMMAND`

Symptom: The CLI says UNKNOWN_COMMAND, sometimes with a “Did you mean” suggestion. Cause: The command name is wrong, or it is a subcommand of another group. Fix: Use help at the level you are on:

sitegpt --help
sitegpt knowledge --help
sitegpt knowledge documents --help

For example, the correct names are sitegpt knowledge documents list, sitegpt knowledge custom-responses list, and sitegpt knowledge sources list.

The CLI still uses an old token

Symptom: You created a new token, but commands still act as the old one. Cause: Creating a token does not change your local profile. Or SITEGPT_API_TOKEN is set, and the CLI uses it instead of any saved profile. Fix:

Run unset SITEGPT_API_TOKEN if you do not need it.
Save the new token:
sitegpt login --token YOUR_NEW_TOKEN
Or save it as its own profile with --profile knowledge-agent.
Run sitegpt whoami to confirm.

Old test profiles still show

Symptom: sitegpt profiles list shows profiles you no longer use. Cause: Profiles stay in the local config file until you delete them. See Where tokens are stored. Fix:

Delete the profile:
sitegpt profiles delete local-test

Revoke its token in SiteGPT. Deleting a profile does not revoke it.

sitegpt tokens list --include-revoked
sitegpt tokens revoke <token-id>

Table output leaves out fields

Symptom: The table does not show a field you need, or shows shortened text. Cause: Table output shows full IDs, but it shortens long text such as emails, titles, and messages. It also leaves out nested data. Fix: Add --json:

sitegpt conversations list --chatbot YOUR_CHATBOT_ID --json

Content stays in processing or fails

Symptom: New documents do not finish, or some show as failed. Cause: SiteGPT is still processing the content, or processing failed for some documents. Fix:

Check the status:

sitegpt dashboard --chatbot YOUR_CHATBOT_ID
sitegpt knowledge documents list --chatbot YOUR_CHATBOT_ID --status PROCESSING
sitegpt knowledge documents list --chatbot YOUR_CHATBOT_ID --status FAILED

Resync the failed documents:

sitegpt knowledge documents resync --chatbot YOUR_CHATBOT_ID --state failed

`rawFileUrl` or `parsedTextFileUrl` is empty

Symptom: These fields are null in document details. Cause: They exist only when the document has those files. Some sources and older documents do not. Fix: None is needed. To see the document content when it exists, run:

sitegpt knowledge documents get --chatbot YOUR_CHATBOT_ID <document-id> --content --json

A connected source shows no documents

Symptom: You authorized a source, but it has no documents. Cause: No files or pages were selected during authorization. For Notion, you select pages and databases inside the Notion authorization. Fix: Authorize the source again and select the files or pages. Then list and add the documents:

sitegpt knowledge sources authorize --chatbot YOUR_CHATBOT_ID <source-id>
sitegpt knowledge sources documents --chatbot YOUR_CHATBOT_ID <source-id>
sitegpt knowledge sources ingest --chatbot YOUR_CHATBOT_ID <source-id>

File upload fails

Symptom: sitegpt knowledge files add fails. Cause: The command takes local file paths only, not URLs. Fix: Download a remote file first. Then pass the local path:

sitegpt knowledge files add --chatbot YOUR_CHATBOT_ID ./guide.pdf

Still stuck

Collect this output and send it to SiteGPT support. Remove tokens from the output first.

sitegpt --version
sitegpt profiles list --json
sitegpt whoami --json
sitegpt --debug whoami

API errors include a request ID. Include it in your message.

Get started

Chatbot setup

Operations

Agent playbooks

Reference

Before you start

`PROFILE_NOT_CONFIGURED`

`PLAN_UPGRADE_REQUIRED`

`HIPAA_AI_ASSISTANTS_DISABLED`

`DEVICE_LOGIN_EXPIRED`

The CLI calls the wrong SiteGPT URL

`NON_JSON_RESPONSE`

`TOKEN_SCOPE_NOT_ALLOWED` or `TOKEN_SCOPE_NOT_VALID`

`UNKNOWN_COMMAND`

The CLI still uses an old token

Old test profiles still show

Table output leaves out fields

Content stays in processing or fails

`rawFileUrl` or `parsedTextFileUrl` is empty

A connected source shows no documents

File upload fails

Still stuck

​Before you start

​PROFILE_NOT_CONFIGURED

​PLAN_UPGRADE_REQUIRED

​HIPAA_AI_ASSISTANTS_DISABLED

​DEVICE_LOGIN_EXPIRED

​OPTIONS_CONFLICT during login

​The CLI calls the wrong SiteGPT URL

​NON_JSON_RESPONSE

​TOKEN_SCOPE_NOT_ALLOWED or TOKEN_SCOPE_NOT_VALID

​UNKNOWN_COMMAND

​The CLI still uses an old token

​Old test profiles still show

​Table output leaves out fields

​Content stays in processing or fails

​rawFileUrl or parsedTextFileUrl is empty

​A connected source shows no documents

​File upload fails

​Still stuck

Before you start

`PROFILE_NOT_CONFIGURED`

`PLAN_UPGRADE_REQUIRED`

`HIPAA_AI_ASSISTANTS_DISABLED`

`DEVICE_LOGIN_EXPIRED`

`OPTIONS_CONFLICT` during login

The CLI calls the wrong SiteGPT URL

`NON_JSON_RESPONSE`

`TOKEN_SCOPE_NOT_ALLOWED` or `TOKEN_SCOPE_NOT_VALID`

`UNKNOWN_COMMAND`

The CLI still uses an old token

Old test profiles still show

Table output leaves out fields

Content stays in processing or fails

`rawFileUrl` or `parsedTextFileUrl` is empty

A connected source shows no documents

File upload fails

Still stuck