---
tags: [tech-patterns, auto-generated]
source: video-accessibility
created: 2026-05-07
---

# Recovering Corrupted Caption Metadata After Failed Translations

## When to use
When VTT caption files exist in cloud storage (GCS) but their URI references have been deleted from document metadata due to translation pipeline failures, resulting in "VTT must start with WEBVTT" errors when serving captions through APIs.

## Prerequisites
- VTT caption files already stored in GCS
- Document metadata layer separate from actual file storage
- Translation pipeline with error handling that may clear metadata on failure
- Access to re-translation or metadata repair mechanism

## Steps
1. Identify affected languages by checking for null/empty `captions_vtt_gcs` values in document outputs despite files existing in GCS
2. Verify the actual VTT files are present and valid in cloud storage
3. For each affected language, trigger the "Re-translate from EN" operation
4. Monitor the re-translation job to completion
5. Verify `captions_vtt_gcs` URI is now correctly populated in document metadata
6. Confirm API returns valid VTT content (starting with "WEBVTT" header)

## Key Configuration
- Document metadata field: `captions_vtt_gcs`
- Expected VTT format: Files must begin with `WEBVTT` header
- Affected case: EN-aligned languages where retranslation was attempted before bug fixes were deployed

## Gotchas
- **Root cause pattern:** Old retranslation attempts triggered error paths that cleared `captions_vtt_gcs` from outputs without deleting the actual GCS files, creating orphaned files with missing metadata references
- **Silent failure:** API returns empty string instead of file URL when URI is null, making the root cause non-obvious
- **Scope:** Only EN-aligned languages with pre-deployment translation attempts are affected; fresh translations after fix are unaffected

## Source
Project: video-accessibility
