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

> ## Agent Instructions
> Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management.
> Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions.
> Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome.
> Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements.

# Troubleshoot a failed command

> Diagnose configuration, authentication, permission, and request errors, and check whether interrupted work completed.

Start with the exact command, exit status, and effective context. A successful login establishes an identity; the requested resource still needs to be accessible to that identity. CLI command syntax in these docs targets version **0.6.134**. For supported installation environments, see [installation](https://docs.thinkplatform.ai/cli/get-started/installation.md).

## Establish what failed

Run these reads using the same profile and environment as the failing command:

```bash theme={"system"}
tp --version
tp context show
tp auth whoami
tp context orgs
```

`context show` reports effective local settings; it does not prove the API is reachable. `auth whoami` makes an authenticated API request. After selecting an authorized organization from the response, discover its projects:

```bash theme={"system"}
tp --org-id "$ORG_ID" context projects
```

Use the discovered organization and project explicitly when reproducing the resource read. [Projects and profiles](https://docs.thinkplatform.ai/cli/guides/context.md) explains setting precedence. A shell, scheduled process, or managed workspace can use a different profile, credential, or environment from your interactive terminal.

## Diagnose by symptom

| Symptom | Check | Next action |
| - | - | - |
| `No such command`, `No such option`, or usage exit status `2` | `tp --version` and the exact command's `--help`. Global options go before the command path. | Correct the syntax or use a client version that supports the documented command. Do not retry the same invalid invocation. |
| Missing organization or project context | Effective context and the IDs discovered above. | Pass `--org-id` and `--project-id` for the intended resource. |
| Token acquisition or interactive login failure | Auth mode and deployment-provided connection settings in [authentication](https://docs.thinkplatform.ai/cli/get-started/authentication.md). | Complete the authorized login flow or correct the credential configuration. Unattended execution needs a credential prepared for that environment. |
| HTTP `401` | Identity, audience, base URL, and credential validity. | Resolve authentication before repeating the operation. See the SDK's [refresh behavior](https://docs.thinkplatform.ai/python-sdk/errors.md#retry-behavior) when using Python. |
| HTTP `403` | Identity **and** organization/project/resource access. | Ask the deployment administrator for the specific operation and resource access required. Changing context or logging in again does not grant permissions. |
| HTTP `404` | Base URL, resource ID, context, and whether the resource still exists. | Rediscover it through an authorized listing. The status alone cannot distinguish a missing resource from every deployment's access-hiding behavior. |
| HTTP `400` or another validation response | Option types, request body, required fields, and current resource schema. | Correct the request. For DB writes, inspect the table's current schema; for API calls, inspect the deployed operation definition. |
| A conflict or stale-version response | Current resource state and the update's version condition. | Read again and reconcile changes. [Canvas updates](https://docs.thinkplatform.ai/cli/guides/canvas-pages.md) use `updatedAt` conflict protection; do not bypass it just to suppress an error. |
| HTTP `429`, server `5xx`, or a transport failure | Response diagnostics and whether the operation can safely be repeated. | For safe reads, use a bounded retry policy and honor a supplied `Retry-After` value. For writes, establish the outcome before repeating. These statuses do not imply a universal CLI retry policy. |
| A successful command followed by invalid JSON parsing | The specific command's output mode. | Separate stdout/stderr and inspect the output contract. Logs, downloads, Markdown, and JSONL are not necessarily one JSON document. |

These are diagnostic starting points, not a universal error schema for every deployed endpoint. Preserve the actual response privately when further diagnosis is needed.

## A user can read, but an Agent cannot

Compare the successful and failing environments, rather than assuming they share credentials:

1. Verify the API base URL and effective organization/project IDs.
2. Inspect the identity using `auth whoami` in each environment. A managed workspace may use workspace delegation instead of the user's interactive credential.
3. Confirm that the failing identity can discover the required organization/project and perform a small read of the intended resource.
4. Ask the administrator to check that identity's access to the named operation and resource. Use the deployment's actual permission vocabulary; there is no documented universal permission flag that fixes every endpoint.

Reading a project does not establish permission to upload files, start a job, invoke an Agent, or change a database row. Request the access needed for the actual workflow. Bundled local [Agent skills](https://docs.thinkplatform.ai/cli/guides/agent-setup.md) teach commands; installing them does not grant platform permissions.

## Recover an uncertain write or run

A timeout or interrupted terminal can occur after the service accepted a request. Capture a returned operation/resource ID if one is available. Then inspect the resource or execution status using the appropriate read commands in [execution workflows](https://docs.thinkplatform.ai/cli/guides/execution.md).

For a create without a returned ID, inspect the relevant collection and reconcile candidate resources using your intended attributes and context before deciding whether to submit again. A second create or run may duplicate work. A failure in output projection with `--query` can also happen after a write succeeded. Removing the projection and reading current state helps establish what happened.

An expired polling timeout is a limit on how long your client waited; it is not evidence that the remote operation was canceled. Inspect its current status before starting another run.

## Share a useful diagnostic report

Include the client version, command path and option names, operation and approximate time, exit status, HTTP status if present, and the expected versus observed behavior. Include a request/correlation identifier only when the service supplies one; the client does not guarantee a common field across all APIs.

Redact access tokens, SAS query strings, credentials, private paths, resource contents, and sensitive error bodies before sharing logs. For reproducible scripting, see [scripting and output](https://docs.thinkplatform.ai/cli/guides/automation.md). Python callers should catch the documented [SDK exceptions](https://docs.thinkplatform.ai/python-sdk/errors.md) rather than assume CLI exit codes apply to Python.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.