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

> Diagnose origin API requests in a Tensor9 BYOC deployment.

For an adapter issue in Tensor9 BYOC, record the application version, test or customer appliance, target cloud, origin service and operation. The same origin request may reach different backends in different deployments, so identify the actual mapping before comparing results.

## Capture one request

Record its timestamp, endpoint, status, error code and response headers. Preserve the exact request identifiers returned by the adapter. Redact credentials, signed URLs, session tokens and sensitive payloads before sharing a reproduction or logs.

Do not enable unrestricted SDK wire logging in a customer environment merely to collect identifiers. Wire logs can contain authentication material and application data. Use scoped collection and the customer's approved access and handling procedures.

## Read the diagnostic headers

| Header                                              | Interpretation                                                                                                                   |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `x-amz-request-id`                                  | Correlation identifier for an S3-shaped response.                                                                                |
| `x-amz-id-2`                                        | Additional S3 response identifier, when present.                                                                                 |
| `x-amzn-requestid`                                  | Correlation identifier used by AWS-shaped responses such as KMS and Parameter Store.                                             |
| `x-tensor9-request-effect: refused-nothing-written` | A specific failed-request path was refused before it wrote anything. Current emission is limited to particular EC2 VPC failures. |

Request identifiers are not proof that a backend operation completed or that a retry is safe. The request-effect header is not emitted by every adapter or every failure path.

**An absent or unrecognized request-effect value means the effect is unknown.** Check resource state and the operation's idempotency rules before retrying a write. A timeout can occur after the backend performed the operation.

Python clients using Botocore response dictionaries expose headers in `ResponseMetadata.HTTPHeaders`. A caught `ClientError` has its response dictionary on `error.response`; a transport exception may have no HTTP response. Collect only the metadata needed for the investigation.

## Trace the deployment-specific path

Check the origin client endpoint, adapter configuration, backend identity and the resource state in the customer's target environment. Distinguish origin authorization from backend permissions. An application's ordinary network traffic or native database protocol may follow a different path from its cloud-management API calls.

Use response identifiers to find the corresponding adapter logs in your approved observability workflow. Preserve relevant [tuning tags](/byoc/service-adapters/tuning/overview), including tags set during resource creation. An empty test resource can hide a state-dependent bug.

## Reproduce in a test appliance

Prefer a test appliance with the same form factor and a minimal workload. Use synthetic data and scoped credentials. Reproduce the setup that matters to the request, then compare the observed result with the service's operation coverage and documented differences.

Do not replay a mutating request in a customer appliance merely to get a cleaner error. Determine whether the original request already changed resources and obtain appropriate authorization before any further live action.

## Use coding agents with captured evidence

The service reference, diagnostic response headers and captured logs can help identify the selected mapping and relevant limits. Documentation cannot establish what happened in a particular live request, and an investigation must not silently replay mutations against customer resources.

You can ask Codex, Claude or another coding agent to investigate a sanitized reproduction through public CLI help and documentation. Give it explicit limits, for example:

```text theme={null}
Investigate this Tensor9 BYOC adapter error using the sanitized evidence and
the named test appliance only. Identify the installed CLI and application
versions, selected backend and relevant service-reference limitations.

Do not access customer credentials, send traffic to customer endpoints,
change deployments, retry the captured write, or delete resources.

Inspect public CLI help before using any command. Do not invent flags or
assume a diagnostic command is isolated from customer resources.

Report observations separately from hypotheses and propose the smallest
safe next test. Ask before performing an action outside these limits.
```

The agent does not need Tensor9 source code or a new standalone Cloud Adapter installation. Review its evidence and suggested actions under your existing BYOC operations and customer-access controls.

## Report an unresolved issue

Include versions, mapping, operation, timestamp, request identifiers, redacted error and configuration, relevant tags, reproduction steps and expected behavior. State what you verified about side effects and whether the issue also occurs in a test appliance. Share the smallest useful evidence bundle, not the customer's complete logs.