> ## Documentation Index
> Fetch the complete documentation index at: https://sitegpt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common SiteGPT CLI authentication, profile, permission, output, and knowledge-ingestion issues.

Start with the basics:

```bash theme={null}
sitegpt --version
sitegpt whoami
sitegpt profiles list
sitegpt chatbots list
```

Use `--json` when you need exact error details:

```bash theme={null}
sitegpt whoami --json
```

## The CLI opens the wrong SiteGPT URL

Check your active profile:

```bash theme={null}
sitegpt profiles list
sitegpt profiles show
```

If a local profile is default, switch back to production:

```bash theme={null}
sitegpt profiles use default
```

Or log in again with the production API base:

```bash theme={null}
sitegpt login --profile default --api-base https://sitegpt.ai
```

Environment variables override saved profiles:

```bash theme={null}
echo $SITEGPT_API_BASE
echo $SITEGPT_PROFILE
```

Unset them if they point to a local environment.

```bash theme={null}
unset SITEGPT_API_BASE
unset SITEGPT_API_TOKEN
unset SITEGPT_PROFILE
```

Then retry:

```bash theme={null}
sitegpt whoami
sitegpt chatbots list
```

## `Unexpected token '<' ... is not valid JSON`

This usually means the CLI expected an API JSON response but received an HTML page. Common causes:

* `SITEGPT_API_BASE` points to the wrong host.
* A saved profile uses a local API base.
* You are using an old CLI version.
* The API route is not deployed yet in the selected environment.

Fix:

```bash theme={null}
sitegpt profiles list
sitegpt profiles show
sitegpt login --profile default --api-base https://sitegpt.ai
npm install -g @sitegpt/cli@latest
```

## Permission or scope errors

Example:

```text theme={null}
TOKEN_SCOPE_NOT_ALLOWED
TOKEN_SCOPE_NOT_VALID
```

Check the command's required area and create a token with the right scopes:

```bash theme={null}
sitegpt login \
  --profile knowledge-agent \
  --scope account:read \
  --scope chatbots:read \
  --scope knowledge:read \
  --scope knowledge:write
```

If the token is chatbot-scoped, confirm the chatbot is included:

```bash theme={null}
sitegpt chatbots list --profile knowledge-agent
```

<Note>
  Token creation is role-aware. If your dashboard role cannot access a chatbot or action, your token cannot grant that access either.
</Note>

## A command says `UNKNOWN_COMMAND`

Use contextual help at the level you are on:

```bash theme={null}
sitegpt --help
sitegpt knowledge --help
sitegpt knowledge documents --help
sitegpt settings --help
```

Also verify the command name. For example:

```bash theme={null}
sitegpt knowledge documents list
sitegpt knowledge custom-responses list
sitegpt knowledge sources list
```

## IDs are shortened in table output

Human table output may shorten long IDs. Use JSON for complete IDs:

```bash theme={null}
sitegpt conversations list --chatbot <chatbot-id> --json
sitegpt knowledge documents list --chatbot <chatbot-id> --json
```

## Profiles from local testing still appear

This is expected. Profiles are stored locally at:

```text theme={null}
~/.config/sitegpt/config.json
```

Delete profiles you no longer use:

```bash theme={null}
sitegpt profiles delete local-test
```

This only deletes local credentials. Revoke the server-side token separately if needed:

```bash theme={null}
sitegpt tokens list --include-revoked
sitegpt tokens revoke <token-id>
```

## Knowledge documents are still processing

Check dashboard summary and document status:

```bash theme={null}
sitegpt dashboard --chatbot <chatbot-id>
sitegpt knowledge documents list --chatbot <chatbot-id> --status PROCESSING
sitegpt knowledge documents list --chatbot <chatbot-id> --status FAILED
```

Resync failed documents:

```bash theme={null}
sitegpt knowledge documents resync --chatbot <chatbot-id> --state failed
```

## Raw or parsed file URLs are empty

`rawFileUrl` and `parsedTextFileUrl` are available only when the underlying ingested document has those files. For some sources or older documents, these fields can be `null`.

To fetch document details and content when available:

```bash theme={null}
sitegpt knowledge documents get --chatbot <chatbot-id> <document-id> --content --json
```

## Source connection authorized but no documents show

For picker-based connectors, rerun authorization on the existing source to select more files:

```bash theme={null}
sitegpt knowledge sources authorize --chatbot <chatbot-id> <source-id>
sitegpt knowledge sources documents --chatbot <chatbot-id> <source-id>
sitegpt knowledge sources ingest --chatbot <chatbot-id> <source-id>
```

For Notion, page/database selection happens inside Notion authorization. If no pages were selected, documents may remain empty until you authorize again and select pages.

## File upload command fails

Use local file paths:

```bash theme={null}
sitegpt knowledge files add --chatbot <chatbot-id> ./guide.pdf
```

If the asset is remote, download it first and then pass the local path.

## Token was created but the CLI still uses an old token

Creating a token does not automatically switch your local profile. Save it with:

```bash theme={null}
sitegpt login --token <new-token>
```

Or create a separate profile:

```bash theme={null}
sitegpt login --profile knowledge-agent --token <new-token>
sitegpt --profile knowledge-agent whoami
```

## Need a clean production profile

```bash theme={null}
sitegpt profiles list
sitegpt profiles delete local-test
sitegpt login --profile default --api-base https://sitegpt.ai
sitegpt profiles use default
sitegpt whoami
```

## Useful debug commands

```bash theme={null}
sitegpt --version
sitegpt profiles list --json
sitegpt profiles show --json
sitegpt whoami --json
sitegpt chatbots list --json
sitegpt dashboard --chatbot <chatbot-id> --json
```