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

# Debugging Your Adapters

> Trace a failed request, preserve response evidence and reproduce safely.

Start with one request and identify the origin service, operation, selected backend and adapter version. Separate a connection failure from an origin API rejection and from an error returned after backend work began.

## Capture the response before retrying

Record the timestamp, operation, endpoint, status, error code, request identifiers and diagnostic headers. Preserve the original error message with secrets removed. A timeout or failed response does not establish that the operation made no changes.

Use the [response-header guide](/cloud-adapter/debugging/response-headers) to distinguish request correlation from statements about a failed request's effects. Avoid logging authorization headers, session tokens, signed URLs, encryption material or sensitive request bodies.

## Follow the evidence loop

Use this order for every incident:

1. **Capture:** preserve the request, response, headers, timestamp and adapter version.
2. **Identify:** name the origin service, operation, backend and configuration revision.
3. **Inspect:** correlate headers with adapter logs and read target state before retrying a mutation.
4. **Reproduce:** reduce the case to one operation with local emulators where they implement the required behavior.
5. **Explain:** use `tensor9 explain` in isolation; do not ask an agent to mutate live resources.
6. **Report:** include the smallest reproduction, expected result and what you verified about side effects.

| Symptom                           | First boundary to check                              |
| --------------------------------- | ---------------------------------------------------- |
| Connection refused or TLS failure | Endpoint, network path and adapter listener          |
| Origin authentication error       | Origin credential, region, signing and endpoint      |
| Adapter rejection                 | Published operation, configuration and request shape |
| Backend authorization error       | Runtime identity and target resource policy          |
| Timeout after a write             | Target state and idempotency before retrying         |

## Check each part of the path

1. **Client:** Is the configured endpoint the adapter you intended to call? Is the operation supported?
2. **Adapter:** Does its configuration select the expected backend? Does the response identifier appear in its logs?
3. **Backend:** Can the configured runtime identity reach the service and access the relevant resource?
4. **Resource state:** Does the resource already exist, or depend on a previous create, policy update or tuning tag?

Check both origin-side authorization and backend-side permissions. A target-cloud permission fix does not correct an invalid origin credential, and an accepted origin request does not prove the backend identity has permission to complete it.

## Build the smallest useful reproduction

Reduce the issue to one operation and the state it requires. Use isolated test resources with known cleanup. Preserve relevant configuration, preceding resource creation and tuning tags; an empty test environment may omit the condition that caused the failure.

For ambiguous writes, inspect resource state and the operation's idempotency contract before retrying. Do not repeatedly replay a create request while investigating a lost response.

## Explain the adaptation

The [explain workflow](/cloud-adapter/debugging/explain) describes service behavior and can analyze a specific request. A service profile explains known behavior; live request evidence shows what happened for a particular call.

You can give your existing coding agent the same evidence and a [bounded investigation task](/cloud-adapter/debugging/agents). Keep live mutation and production credentials outside the task unless you explicitly authorize them.

## Prepare a useful report

Include the adapter and client versions, mapping, operation, redacted configuration, relevant tags, exact error and response identifiers, expected result and the smallest reproduction. State whether the issue occurs locally, against the real backend or both. Include what you verified about possible side effects.

If the cause remains unclear, [contact Tensor9](https://www.tensor9.com/contact/) with that evidence. Share sanitized examples first, not complete application logs.