Skip to main content

Troubleshooting Asset Documents

Summary​

This page covers asset document problems. Document bytes live in the document service; the asset service stores references only. Upload and download failures map to error results, and when the document service is unavailable a production fail-safe returns 503. Removing a reference does not delete the external bytes, which creates an orphan-bytes risk; no reconciliation job exists to clean these up.

Audience​

Support engineers and developers investigating failed uploads or downloads, 503 responses on document operations, or concerns about orphaned bytes after a reference removal.

Symptoms​

  • A document upload or download fails with an error result.
  • A document operation returns 503.
  • A reference was removed but the bytes appear to remain.
  • A document reference exists with no reachable bytes.

Cause​

Scope​

This page covers the reference model, the fail-safe behavior, and orphan-bytes risk. It does not cover the internal storage of the document service.

Likely causes​

  • The document service was unavailable, so the production fail-safe returned 503.
  • An upload or download failed and was mapped to an error result.
  • A reference was removed, which does not delete the external bytes, leaving orphaned bytes by design.
  • A reference points at bytes that are not reachable because the underlying object was handled outside the asset service.

Resolution​

Safe diagnostics​

  • Confirm the document service availability when a 503 is observed; the fail-safe indicates the dependency was unavailable.
  • Confirm whether the operation was an upload or download and which error result was returned.
  • Treat reference removal as reference-only; expect the bytes to persist and note the orphan risk rather than assuming deletion failed.
  • Do not expect a reconciliation job to clean up orphaned bytes; none exists.

Validation​

  • Confirm document operations succeed once the document service is available.
  • Confirm that a removed reference no longer appears while acknowledging the bytes remain external.
  • Confirm error results correspond to the observed upload or download failure.

Evidence to Collect​

  • The operation attempted and the response status, including any 503.
  • Whether a reference was removed and when.
  • A correlation identifier and timestamp.
  • The document reference involved.

Escalation​

Route document storage, availability, and byte lifecycle to the document management owner. Route the reference model and fail-safe behavior to the asset or backend team. Orphan-bytes reconciliation ownership is Requires confirmation where no named owner is established.

Source References​

  • microservices/src/asset-service/Infrastructure/DocumentServiceClient.cs
  • microservices/src/asset-service/Api/AssetEndpoints.cs
  • microservices/src/asset-service/Api/EndpointResults.cs

See Also​

Keywords​

documents, references, fail-safe, orphan bytes, 503

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-17
  • Review cycle: Quarterly