> ## 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

> Choose the right Explain workflow, preserve request evidence and investigate without unsafe replay.

When an origin-cloud operation behaves differently in a target environment, start with one request and one question. Identify the origin service and operation, directed target profile, adapter version, configuration revision, resource identity and time window.

Cloud Adapter comes bundled with [Support Agents](https://docs.tensor9.com/cloud-adapter-early-access/support/agents.md). Bring that context to your agent to organize the evidence, compare possible causes and identify the next useful check. [Debugging with Agents](https://docs.tensor9.com/cloud-adapter-early-access/debugging/agents.md) shows how to keep the conclusion tied to observed behavior. Use [Operations with Agents](https://docs.tensor9.com/cloud-adapter-early-access/operations/overview.md) to coordinate the investigation and any separately approved follow-up work.

Then choose the evidence path that matches what you need to know. For deployed-report retrieval, first confirm [installed protocol and CLI support](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#check-installed-support); the examples do not establish availability in older releases.

## Choose a debugging path

| You need to know | Start here | Performs the service operation? |
| - | - | - |
| What the selected origin-to-target profile supports | [Understanding Behavior with Explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain.md) | No |
| What one request would do | A signed, explicit version-1 [`x-t9-explain` control](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers) with mode `Explain` | No |
| What an existing SDK request attempted and observed | [Explaining SDK Requests](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md) with `ExecuteAndExplain` | Yes |
| What an existing report establishes | [Reading an Explanation](https://docs.tensor9.com/cloud-adapter-early-access/debugging/reading-explanations.md) | No |
| Whether later target or child work finished | [Following Asynchronous Explanations](https://docs.tensor9.com/cloud-adapter-early-access/debugging/async-explanations.md) | Report reads do not rerun it |
| How to interpret PostgreSQL planning evidence | [PostgreSQL Query Plans in Explain](https://docs.tensor9.com/cloud-adapter-early-access/debugging/postgres-query-plans.md), a planned integration with operation-specific coverage | Report reads do not rerun SQL |
| Why a control, receipt or report is missing | [Troubleshooting Explanations](https://docs.tensor9.com/cloud-adapter-early-access/debugging/troubleshooting.md) | No |
| How to give evidence to a coding agent safely | [Debugging with Agents](https://docs.tensor9.com/cloud-adapter-early-access/debugging/agents.md) | No by default |

> [!WARNING]
>
> `x-t9-explain: true` executes the request and records an explanation. For a preview, add the signed explicit version-1 control with `"mode":"Explain"` before request signing. A completed preview returns a native `409 ExplainedNotPerformed` error with a report receipt. Retrieve the explanation separately through the dedicated synthetic AWS `t9` service using normal IAM credentials and SigV4 signing name `t9`; no diagnostic document replaces the SDK response.

Already have a report receipt? [Retrieve the existing explanation through the signed SDK flow](https://docs.tensor9.com/cloud-adapter-early-access/debugging/explain-sdk.md#retrieve-without-replaying) using the published t9 endpoint, signing region and original owner's AWS credentials. Decode the outer AWS JSON response's `body` string. The read neither launches an adapter nor acknowledges the report.

## Follow one evidence loop

1. **Capture the original result.** Preserve status, error code, request identifiers, Explain receipt headers and timestamp before a retry changes the evidence.
2. **Identify the exact path.** Record origin service, operation, target profile, endpoint, adapter version, configuration revision and resource identity.
3. **Classify the question.** Decide whether you need profile coverage, a non-executing preview, executed evidence or an existing report read.
4. **Inspect the target state.** A failed or timed-out write can still have effects. Use a service-specific read before replaying it.
5. **Follow evidence IDs.** Connect decision events to observed, derived and hypothetical facts. Retain limitations and unknowns.
6. **Choose one bounded next action.** Prefer a non-mutating state read or isolated test that resolves one uncertainty.
7. **Share a sanitized bundle.** Preserve stable IDs while removing credentials and sensitive payloads.

## Separate the failure boundaries

| Symptom | First boundary to inspect |
| - | - |
| Connection refused, DNS or TLS failure | Client endpoint and network path; no HTTP response means no receipt |
| Origin authentication error | Origin credentials, region, signing name and signed headers |
| Explain-control refusal | Header grammar, duplicates, mode coverage and signing order |
| Adapter request rejection | Directed service profile, request shape, configuration and named constraint |
| Target authorization error | Adapter runtime identity and target resource policy |
| Timeout after a write | Target state, operation idempotency and existing report; do not replay first |
| Native success with partial report | Preserve both; poll the same report independently |

Origin and target authorization are separate. An accepted origin signature does not prove the target identity has access. A target permission fix does not repair an invalid origin signature.

## Capture response evidence

Record the raw HTTP metadata available through the SDK:

* origin request IDs such as `x-amz-request-id` or `x-amzn-requestid`;
* `x-t9-explain-id`, `x-t9-explain-mode`, `x-t9-explain-expires-at` or `x-t9-explain-unexplained` when present;
* report revision and lifecycle from authorized reads;
* `x-tensor9-request-effect` only when it is explicitly returned;
* status, error code and a redacted body.

The [diagnostic header reference](https://docs.tensor9.com/cloud-adapter-early-access/debugging/response-headers.md) defines each header's narrow meaning. A report receipt is not proof of completion or successful report persistence. An absent request-effect header means effect unknown.

Avoid full wire logging by default. Signed requests can expose authorization material and application data.

## Reproduce safely

Reduce the case to one operation and the state it requires. Use isolated test resources with known ownership and cleanup. Preserve the condition that caused the failure: configuration, existing resources, preceding operations and supported tuning tags can all matter.

A profile inspection requires Tensor9 authentication and the matching entitlement, but it is safe to run without an origin or target provider account. An `Explain` preview does not perform the requested service action. An `ExecuteAndExplain` request is a real execution and requires the same approval, resource boundaries and cleanup as the ordinary operation.

Do not treat stopping a local adapter as target cleanup. Verify target resources separately.

## Use worked investigations with the same scope

[Adapter Investigation Playbooks](https://docs.tensor9.com/cloud-adapter-early-access/debugging/worked-examples.md) show how to connect a profile, exact request, report evidence and target-state check. Reuse their method, not conclusions from a different service or backend. Evidence from an S3 emulator does not qualify DynamoDB-to-Cosmos behavior or a messaging delivery path.

## Prepare a useful support report

Follow [Getting Help](https://docs.tensor9.com/cloud-adapter-early-access/support/getting-help.md) for a step-by-step evidence handoff. [How Support Works](https://docs.tensor9.com/cloud-adapter-early-access/support/overview.md) explains the adapter and target-service boundary. You can open a case while the cause is still unknown.

Include adapter and SDK versions, origin/target mapping, operation, redacted configuration, exact mode, relevant tags, native result, receipt identifiers, report revision and assurance, expected behavior and observed target state. State whether the issue occurs locally, with an emulator, against a test provider account or in a customer deployment.

List what you verified about side effects and what remains unknown. Share sanitized examples first, not complete logs. Have your support agent retain its findings, evidence references and unresolved questions with the case. When human Tensor9 help is needed, carry that context through your agreed support channel or [contact Tensor9](https://www.tensor9.com/contact/). Report active production incidents through the agreed incident channel while the investigation continues.


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