Skip to main content
Troubleshoot the service operation and the explanation system as separate paths. A target operation can succeed while its report is temporarily unavailable. A complete report can accurately describe an operation that was refused. A missing report never proves that a write had no effect. Start by preserving the original request time, exact endpoint, operation, mode, response status, origin request IDs, Explain receipt headers and observed target state. Remove credentials and sensitive payload data.

​
Symptom and next-action matrix

​
Failure 1: the control was added after signing

​
Symptom

The request is refused as an unsigned Explain control, even though the application appears to send a valid value.

​
Why it happens

x-t9-explain changes whether the request executes and must be integrity-protected. If an HTTP interceptor appends the header after SigV4 signing, the adapter cannot trust it. A reverse proxy can cause the same problem if it adds or rewrites the control after the client signs.

​
Confirm it

Inspect request construction without printing the authorization credential:
  1. Identify where endpoint selection, request override and signing occur.
  2. Confirm x-t9-explain is present before the signer runs.
  3. Check that the signed-header set covers it.
  4. Confirm there is exactly one value and that no proxy rewrites it.

​
Fix it

In AWS SDK for Java 2.x, use request override configuration while building the service request:
The SDK applies the override before signing. Do not add a second copy in a generic HTTP interceptor.

​
What not to do

Do not remove the header and send the mutation normally just to see whether the endpoint works. Use a non-mutating operation or fix signing first.

​
Failure 2: the operation succeeded but the report is unavailable

​
Symptom

An ExecuteAndExplain call returned its native success and x-t9-explain-id, but reading the report returns 404 NotFound, 503 Unavailable or remains partial.

​
Interpretation

The origin operation and report have separate lifecycles. Native success is evidence about the origin API response. It does not seal the report. A report receipt identifies correlation intent; it does not prove that a report row was persisted. Report unavailability is evidence about the diagnostic read path, not a rollback of target effects.

​
Safe response

  1. Preserve the native response, origin request ID, report ID and target resource identity.
  2. Verify the intended target state using the service’s normal read path.
  3. Retry only the signed T9CloudAdapter.GetExplanation call through t9 with bounded backoff and the same owner identity.
  4. If an origin status operation exists, query the exact resource identity independently. Supply the report ID to GetExplanation, signed as t9 at the configured report endpoint and region.
  5. Record the latest report revision; ignore a late older revision.
  6. Do not replay the mutating operation merely to create another report.
If the report never becomes available, the operation’s native evidence and target-state observation remain the source for deciding cleanup or remediation. Report absence must be recorded as a diagnostic limitation. Do not guess another report ID.

​
Failure 3: an explicit mode is unsupported

​
Symptom

The application explicitly requests Explain or ExecuteAndExplain, and the adapter refuses before the operation runs.

​
Interpretation

An explicit request is fail-closed. The adapter does not silently ignore it, fall back to the adapter default or execute normally. This protects a preview from becoming a mutation.

​
Safe response

  1. Read the exact refusal and origin operation.
  2. Inspect the directed service profile and operation-specific coverage.
  3. Confirm that the deployed adapter and selected target match the profile you inspected.
  4. Choose a supported non-mutating operation for connectivity testing, or collect ordinary service evidence without claiming an explanation.
Do not switch to x-t9-explain: true as a workaround: that value means ExecuteAndExplain, not a more compatible preview.

​
Malformed, duplicate and false controls

The adapter refuses these controls before ordinary service processing:
The first has no off spelling; omit the header for ordinary execution. The second lacks version. The third uses the wrong enum case. The fourth contains an unknown field. Empty, non-ASCII, over-4096-byte and repeated fields are also refused. Log a redacted representation of the control and its byte length, not the complete signed request.

​
Default-caused unexplained requests

When an adapter default asks for explanation but a declared status read must execute ordinarily, the response can include:
This says the default was not applied and no report was opened. It is not an error-provenance header and not a report receipt. An explicit unsupported Explain request is refused instead of receiving this fallback. Check the operation’s coverage and whether your client intended an ordinary status read or a separate GetExplanation call through t9. Query resource status by its exact resource identity; retrieve explanation content only with GetExplanation, passing the report ID in its JSON request.

​
Missing receipt

No x-t9-explain-id can have several causes:
  • the request never reached an HTTP service;
  • no explicit control or adapter default applied;
  • the operation was served under default fallback and has x-t9-explain-unexplained;
  • the request was refused before report creation, including some authorization paths;
  • middleware removed response headers;
  • the client inspected only a decoded error and discarded raw HTTP metadata.
Do not collapse these cases. First establish whether an HTTP response arrived, then preserve its raw status and headers. For example, an S3 authorization denial occurs before a report opens; the inspected VPC path can represent an authenticated denial. Report behavior is service-specific, not a universal policy-trace promise.

​
Report read dispositions

Use the status and disposition together:
  • 409 NotYetVisible means the stored revision is below the GetExplanation request’s minimumVersion; retain the previously recorded snapshot, record the current stored revision returned by the disposition, and retry the read.
  • 409 NotSealed or RevisionMismatch applies to acknowledgment; read the current report and use its supplied acknowledgeable revision.
  • 410 Consumed means the owner already acknowledged the sealed revision. Repeating the same owner acknowledgment at the same revision is idempotent; another revision is a mismatch.
  • 410 Expired is terminal while the expired record remains; after retention collection, the same report can appear as 404.
  • 503 Unavailable permits a later read attempt, not a mutation replay.
  • 404 NotFound can mean nonexistent, concealed from this principal, not persisted, unsupported schema or already collected after expiry. Changing the guessed ID is not a discovery mechanism.
Changing the GetExplanation input from "fmt":"Human" to "fmt":"Json" renders the same report. It does not start a new report, fill missing evidence or renew retention. The default deadline is 24 hours from creation. Check x-t9-explain-expires-at or the JSON report’s reportExpiresAt; see retention and expiry for configuration and physical collection.

​
SDK response decoding and retries

Service responses retain their origin protocol. A completed Explain preview returns 409 ExplainedNotPerformed with a report receipt, which the SDK can handle as a service error. Its explanation is retrieved by GetExplanation on t9, signed as t9 with the configured endpoint and region. ExecuteAndExplain returns the native execution result with receipt headers. Capture receipt headers before unmarshalling so an SDK decoding failure does not lose a received report ID. Keep the native error, each attempt’s report ID, and the independent report-read result. A decoding or transport failure does not establish whether a mutating request had effects. If a service operation returns a diagnostic body or an outer-200 explanation envelope, check the adapter version and endpoint. The legacy x-t9-explain-id request selector is refused with 400 InvalidExplainConfiguration; replace it with a separate GetExplanation call to t9. Changing Accept is not a way to retrieve an inline explanation. Use ExecuteAndExplain when performing the operation is intended. See Explaining SDK Requests. The signed SDK retrieval flow also preserves these dispositions: a failed report read does not execute the service operation. Check the published t9 endpoint, signing region and exact owner credentials before retrying; no Tensor9 API key is required.

​
Endpoint, region and credential mistakes

An origin SDK still signs for its origin service and region while sending to the adapter endpoint. Check these independently:
  • process-wide AWS_ENDPOINT_URL_<SERVICE> or programmatic endpoint override;
  • origin region and signing name;
  • origin credential provider used by the SDK;
  • adapter’s configured target identity;
  • network and TLS path to the adapter.
Fixing target-cloud IAM does not correct an invalid origin signature. Fixing origin credentials does not grant the adapter’s target identity permission. A connection failure before an HTTP response produces no report headers.

​
Build a support bundle

Use your included Support Agents to organize the operation result and report-read problem as separate questions. Keep the attempted checks and remaining uncertainty with the evidence so human support can continue the same investigation when needed. Include:
  • product, adapter and SDK versions;
  • origin, target and operation;
  • exact mode and sanitized control;
  • timestamp, endpoint category and request identifiers;
  • native status/error and Explain receipt headers;
  • report ID, revisions, lifecycle, assurance and limitations;
  • the smallest redacted request shape;
  • observed target state and how it was checked;
  • whether any retry or cleanup ran;
  • what remains unknown.
Exclude credentials, authorization headers, signed URLs, secret payloads and unrelated customer data. Follow Debugging with Agents for evidence-linked analysis and Getting Help to escalate with the findings and open questions. Use your agreed incident channel immediately for an active production incident.