# Troubleshooting your first agent

> Resolve setup failures and distinguish a policy refusal from a service error.

Source: https://docs.atensecurity.com/docs/getting-started/troubleshooting

## Missing package or import

Install **atensec-thoth**, then `import thoth` in Python. Check that your
terminal uses the virtual environment where you installed it. TypeScript uses
`@atensec/thoth` and Node.js 22+; the starter project uses ES modules and `tsx`.
See [Install an SDK](https://docs.atensecurity.com/docs/getting-started).

## Missing key, tenant, or endpoint

Use all three values supplied with your activated tenant. Set `THOTH_TENANT_ID`,
`THOTH_API_URL`, and `THOTH_API_KEY` in the same terminal that runs the example.
Use the unified base URL, without appending `/v1/enforce`. Do not guess a
hostname or use the GovAPI administration endpoint for the SDK.

## 401 or 403

Check key expiry, tenant binding, and execute permission. A provider needs a
separate organization read/write key. A key is only shown once at creation;
rotate it through your administrator if you no longer have it. Never send
plaintext keys in a support request.

## 429, transport errors, or 5xx

Honor retry guidance when present. Avoid rapid retry loops. Keep fail-open
disabled while resolving connectivity or service failures. A refusal caused by
an unavailable service does not prove server policy blocked your tool.

## demo.read is refused

If an earlier run blocked `shell.exec`, the demo agent is quarantined. Ask an
administrator to open **Agents → trial-demo → Restore Agent**, then start again
with `demo.read`. Restore it before switching languages too.

If this is the first run, verify that your tenant has the expected demo policy
and inspect the decision reason with your trial contact.

## shell.exec returns STEP_UP or executes the guard

Stop the demo and reconcile the server policy. The expected result is `BLOCK`.
The example's callback raises an error if reached and never starts a shell.
Changing `approved_scope` does not install the expected policy.

## Activation progress changed, but the result looks wrong

Progress records a first authenticated, finalized decision, including a refused
action. Check decision history separately. Progress alone does not prove an
`ALLOW`, callback execution, or a finalized evidence export.

## Request help

Contact your trial support contact or [support@atensecurity.com](mailto:support@atensecurity.com).
Include the SDK version, timestamp, agent ID, sanitized error, and available
correlation ID. Remove credentials, hold tokens, personal data, and private tool
arguments. Explain the expected decision and the observed result.

[Return to your first governed agent →](https://docs.atensecurity.com/docs/getting-started/quickstart)