Skip to main content
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. Bring that context to your agent to organize the evidence, compare possible causes and identify the next useful check. Debugging with Agents shows how to keep the conclusion tied to observed behavior. Use Operations with Agents 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; the examples do not establish availability in older releases.

​
Choose a debugging path

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

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 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 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 for a step-by-step evidence handoff. How Support Works 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. Report active production incidents through the agreed incident channel while the investigation continues.