Troubleshoot a failed command

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.

Establish what failed

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

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:

tp --org-id "$ORG_ID" context projects

Use the discovered organization and project explicitly when reproducing the resource read. Projects and profiles 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.	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 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 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:

Verify the API base URL and effective organization/project IDs.
Inspect the identity using auth whoami in each environment. A managed workspace may use workspace delegation instead of the user’s interactive credential.
Confirm that the failing identity can discover the required organization/project and perform a small read of the intended resource.
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 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. 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. 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. Python callers should catch the documented SDK exceptions rather than assume CLI exit codes apply to Python.

Get started

CLI

Python SDK

Agent skills

Establish what failed

Diagnose by symptom

A user can read, but an Agent cannot

Recover an uncertain write or run

​Establish what failed

​Diagnose by symptom

​A user can read, but an Agent cannot

​Recover an uncertain write or run

​Share a useful diagnostic report

Establish what failed

Diagnose by symptom

A user can read, but an Agent cannot

Recover an uncertain write or run

Share a useful diagnostic report