oxc-project/oxc · error

Missing `<track>` element with captions inside `<audio>` or

Error message

Missing `<track>` element with captions inside `<audio>` or `<video>` element

What it means

Raised by jsx-a11y/media-has-caption when an <audio> or <video> element does not contain a <track> element with kind="captions". Deaf and hard-of-hearing users cannot access audio content without captions.

Source

Thrown at crates/oxc_linter/src/rules/jsx_a11y/media_has_caption.rs:17

use std::borrow::Cow;

use oxc_ast::{
    AstKind,
    ast::{JSXAttributeItem, JSXAttributeName, JSXAttributeValue, JSXChild, JSXExpression},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::{AstNode, context::LintContext, rule::Rule, utils::get_element_type};

fn media_has_caption_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn(
        "Missing `<track>` element with captions inside `<audio>` or `<video>` element",
    )
    .with_help("Media elements such as `<audio>` and `<video>` must have a `<track>` for captions.")
    .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct MediaHasCaption(Box<MediaHasCaptionConfig>);

#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase", default, deny_unknown_fields)]
pub struct MediaHasCaptionConfig {
    /// Element names to treat as `<audio>` elements
    audio: Vec<Cow<'static, str>>,
    /// Element names to treat as `<video>` elements
    video: Vec<Cow<'static, str>>,
    /// Element names to treat as `<track>` elements
    track: Vec<Cow<'static, str>>,

View on GitHub (pinned to e1e7af627c)

Solutions

1. Add <track kind="captions" src="..." srcLang="..." /> inside the media element.
2. Mark the media as decorative if it has no meaningful audio (per rule configuration).

When it happens

Trigger: Thrown at crates/oxc_linter/src/rules/jsx_a11y/media_has_caption.rs:17 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/ec51b08bd22b7f7f. Report an issue: GitHub.