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. Then choose the evidence path that matches what you need to know.

​
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. An ordinary generated SDK cannot decode that diagnostic document as the operation’s normal success response; use an explanation-aware request path.

​
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 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. If the cause remains unclear, contact Tensor9 with that evidence.