What causes "Invalid Mux URL." in forem/forem?

Use the player URL: https://player.mux.com/

forem/forem · error · StandardError

Invalid Mux URL.

Error message

Invalid Mux URL.

What it means

The {% mux %} input (strip_tags + entity unescape) has its query string removed via split('?').first and must match https://player.mux.com/<video_id> where video_id is [a-zA-Z0-9_-]+ (optionally followed by a well-formed query before stripping). Otherwise the tag raises 'Invalid Mux URL.'. Note UnifiedEmbed registers MuxTag with skip_validation: true, so the {% embed %} path performs no pre-validation — this check inside the tag is the only guard.

Source

Thrown at app/liquid_tags/mux_tag.rb:33

  end

  def render(_context)
    ApplicationController.render(
      partial: PARTIAL,
      locals: {
        id: @id,
        width: @width,
        height: @height
      },
    )
  end

  private

  def extract_video_id(input)
    input_params_removed = input.split("?")[0] # Remove query params for validation
    match = pattern_match_for(input_params_removed, [REGISTRY_REGEXP])
    raise StandardError, I18n.t("liquid_tags.mux_tag.invalid_mux_url") unless match

    match[:video_id]
  end
end

UnifiedEmbed.register(MuxTag, regexp: MuxTag::REGISTRY_REGEXP, skip_validation: true)

View on GitHub (pinned to f354c376a7)

Solutions

Use the player URL: https://player.mux.com/<video_id>
Copy the playback link from the Mux asset's embed/player panel
Keep the id to alphanumerics, dashes and underscores

Example fix

// before
{% mux https://mux.com/assets/abc123 %}

// after
{% mux https://player.mux.com/abc123 %}

Defensive patterns

Strategy: validation

Validate before calling

def valid_mux_url?(raw)
  MuxTag::REGISTRY_REGEXP.match?(raw.split('?').first.to_s)
end

Try / catch

begin
  Liquid::Template.parse(markdown).render
rescue StandardError => e
  [e.message]
end

Prevention

Remember {% embed %} does NOT pre-validate Mux (skip_validation: true) — always lint the player URL yourself
Normalize to https://player.mux.com/<id> at input time

When it happens

Trigger: A non-player.mux.com host (share.mux.com, mux.com dashboard links); a missing video id; an id containing characters outside [a-zA-Z0-9_-]; URLs where removal of '?...' leaves an empty or malformed path.

Common situations: Pasting the Mux dashboard or share.mux.com asset URL instead of the player URL; percent-encoded characters that survive unescaping.

Related errors

AI-assisted analysis of forem/forem@f354c376a7 (2026-08-21). Data as JSON: /api/errors/0a33d7463d2b6cf8. Report an issue: GitHub.