{"record":{"id":"cf8c9fd6b4ccd2e8","repo":"remotion-dev/remotion","slug":"unknown-mp3-header","errorCode":null,"errorMessage":"Unknown MP3 header ","messagePattern":"Unknown MP3 header ","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/containers/mp3/parse-mp3.ts","lineNumber":48,"sourceCode":"\tif (bytes[0] === 0x54 && bytes[1] === 0x41 && bytes[2] === 0x47) {\n\t\tparseID3V1(iterator);\n\t\treturn null;\n\t}\n\n\t// ID3 v2 or v3\n\tif (bytes[0] === 0x49 && bytes[1] === 0x44 && bytes[2] === 0x33) {\n\t\tparseId3({state});\n\t\treturn null;\n\t}\n\n\tif (bytes[0] === 0xff) {\n\t\tawait parseMpegHeader({\n\t\t\tstate,\n\t\t});\n\t\treturn null;\n\t}\n\n\tthrow new Error('Unknown MP3 header ' + JSON.stringify(bytes));\n};\n","sourceCodeStart":30,"sourceCodeEnd":50,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/mp3/parse-mp3.ts#L30-L50","documentation":"Thrown by `parseMp3` when the first three bytes of an MP3 data chunk do not match any recognized signature: not `0x54 0x41 0x47` (ID3v1 `TAG`), not `0x49 0x44 0x33` (ID3v2/v3), and not `0xFF` (MPEG frame sync). The parser treats this as an unrecognized/corrupt MP3 header.","triggerScenarios":"The MP3 parser encounters a data region starting with bytes that match none of the known MP3 signatures. This happens when the file is not actually MP3, is corrupt, or has garbage data between valid frames.","commonSituations":"Passing a non-MP3 file (e.g., WAV, FLAC, OGG) that was misidentified as MP3. Corrupt or partially-downloaded MP3 files. Files with extraneous padding or junk bytes. The parser was pointed at an MP3 stream mid-way through non-audio data.","solutions":["Verify the file is genuinely an MP3 file using `ffprobe -i file.mp3` or checking the magic bytes.","Re-download or re-encode the file if it may be corrupt.","If the file is a different format, use the appropriate parser or convert it to MP3.","Inspect the first few bytes with a hex editor to confirm they start with `FF FB`, `FF F3`, `FF FA`, or `49 44 33` (ID3)."],"exampleFix":"# check the file is valid MP3\nffprobe -i input.mp3\n\n# if not, convert to MP3\nffmpeg -i input.wav -codec:a libmp3lame output.mp3","handlingStrategy":"validation","validationCode":"// Verify file starts with valid MP3 magic bytes\nasync function isLikelyMp3(file: File): Promise<boolean> {\n  const header = new Uint8Array(await file.slice(0, 3).arrayBuffer());\n  // ID3v2\n  if (header[0] === 0x49 && header[1] === 0x44 && header[2] === 0x33) return true;\n  // ID3v1 (TAG)\n  if (header[0] === 0x54 && header[1] === 0x41 && header[2] === 0x47) return true;\n  // MPEG frame sync\n  if (header[0] === 0xff) return true;\n  return false;\n}","typeGuard":null,"tryCatchPattern":"try {\n  await parseMedia({src, fields: {durationInSeconds: true}});\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Unknown MP3 header')) {\n    console.error('The file does not contain valid MP3 data.');\n  }\n  throw e;\n}","preventionTips":["Verify files are genuine MP3 by checking magic bytes or using ffprobe.","Do not pass WAV, FLAC, OGG, or other formats as MP3.","Check for partial downloads or truncation before parsing.","Re-encode from a known-good source if corruption is suspected."],"tags":["mp3","corrupt-file","invalid-header","file-format"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}