What causes "Found {} broken external link(s) {}" in getzola/zola?

Fix or remove the broken external URLs listed in the error output

Found {} broken external link(s) {}

Error message

Found {} broken external link(s)
{}

What it means

In check mode, Zola verifies external (http/https) links. If external_level = "error" and any external links fail to resolve (network error, 404, timeout), load fails with this message listing each broken URL.

Source

Thrown at components/site/src/lib.rs:389

        }

        // check external links, log the results, and error out if needed
        if self.config.is_in_check_mode() && self.check_external_links {
            let external_link_messages = link_checking::check_external_links(self);
            if !external_link_messages.is_empty() {
                let messages: Vec<String> = external_link_messages
                    .iter()
                    .enumerate()
                    .map(|(i, msg)| format!("  {}. {}", i + 1, msg))
                    .collect();
                let msg = format!(
                    "Found {} broken external link(s)\n{}",
                    messages.len(),
                    messages.join("\n")
                );
                match self.config.link_checker.external_level {
                    config::LinkCheckerLevel::Warn => log::warn!("{msg}"),
                    config::LinkCheckerLevel::Error => return Err(anyhow!(msg)),
                }
            }
        }

        Ok(())
    }

    /// Insert a default index section for each language if necessary so we don't need to create
    /// a _index.md to render the index page at the root of the site
    pub fn create_default_index_sections(&mut self) -> Result<()> {
        let mut missing_sections = Vec::new();
        for (index_path, lang) in self.index_section_paths() {
            if let Some(index_section) = self.library.sections.get(&index_path)
                && self.config.build_search_index
                && !index_section.meta.in_search_index
            {
                bail!(
                    "You have enabled search in the config but disabled it in the index section: \

View on GitHub (pinned to 61d3082821)

Solutions

Fix or remove the broken external URLs listed in the error output
Set link_checker.external_level = "warn" in config.toml so broken links warn instead of failing
Run the check on a machine/CI job with working internet access
Exclude unreachable-by-design hosts if the checker offers ignore/skip options, or replace links with a stable archive URL

Example fix

// before: config.toml
[link_checker]
external_level = "error"
// after
[link_checker]
external_level = "warn"

Defensive patterns

Strategy: fallback

Validate before calling

// Pre-check critical external URLs before a release build:
// curl -fsSL -o /dev/null --max-time 10 https://example.com/page || echo BROKEN

Try / catch

// Use warn level so flaky external hosts don't fail builds:
// [link_checker]
// external_level = "warn"
match result {
    Err(e) if e.to_string().contains("broken external link") => {
        log::warn!("continuing despite external link failures: {e}");
    }
    other => other?,
}

Prevention

Run link checks in a scheduled job, not on every build
Set external_level = "warn" for hosts known to block bots
Periodically audit external links and replace dead ones with archive.org snapshots

When it happens

Trigger: zola check with check_external_links enabled and a linked external URL returns a non-success status or cannot be reached; external_level = "error" in config link_checker.

Common situations: Dead external links after third-party sites moved or shut down; CI running checks without network access; rate-limited or bot-blocked hosts (e.g. GitHub, social media) returning 4xx/5xx; temporary network outages.

Related errors

AI-assisted analysis of getzola/zola@61d3082821 (2026-09-03). Data as JSON: /api/errors/fbb0862e5c456c83. Report an issue: GitHub.