quickwit-oss/quickwit · error

unknown URI protocol `{protocol}`

Error message

unknown URI protocol `{protocol}`

What it means

`Protocol::from_str` in quickwit-common's uri module maps URI scheme strings to the `Protocol` enum, accepting a fixed set: http/https/grpc/actor/pg (postgres, postgresql)/ram/s3/gs. Any other scheme is rejected with this error. Quickwit URIs are scheme-dispatched (where to read/write data), so an unrecognized scheme cannot be resolved to a storage backend.

Source

Thrown at quickwit/quickwit-common/src/uri.rs:92

    fn fmt(&self, formatter: &mut std::fmt::Formatter) -> std::fmt::Result {
        write!(formatter, "{}", self.as_str())
    }
}

impl FromStr for Protocol {
    type Err = anyhow::Error;

    fn from_str(protocol: &str) -> anyhow::Result<Self> {
        match protocol {
            "azure" => Ok(Protocol::Azure),
            "file" => Ok(Protocol::File),
            "grpc" => Ok(Protocol::Grpc),
            "actor" => Ok(Protocol::Actor),
            "pg" | "postgres" | "postgresql" => Ok(Protocol::PostgreSQL),
            "ram" => Ok(Protocol::Ram),
            "s3" => Ok(Protocol::S3),
            "gs" => Ok(Protocol::Google),
            _ => bail!("unknown URI protocol `{protocol}`"),
        }
    }
}

const PROTOCOL_SEPARATOR: &str = "://";

/// Encapsulates the URI type.
///
/// URI's string representation are guaranteed to start
/// by the protocol `str()` representation.
///
/// # Disclaimer
///
/// Uri has to be built using `Uri::from_str`.
/// This function has some normalization behavior.
/// Some protocol have several acceptable string representation (`pg`, `postgres`, `postgresql`).
///
/// If the representation in the input string is not canonical, it will get normalized.

View on GitHub (pinned to a39730c5cd)

Solutions

1. Use a supported scheme: `s3://`, `gs://`, `ram://`, `grpc://`, `actor://`, or `pg://`/`postgres://`/`postgresql://`.
2. For local filesystem storage, use a plain absolute path (e.g. `/data/quickwit`) rather than `file://`.
3. Check the scheme's spelling and casing, and that the matching cloud-storage feature is compiled in if the scheme is valid but unsupported in this build.
4. If migrating from an older config, update URIs to the current protocol names.

Example fix

// before
let uri: Uri = "file:///data/quickwit".parse()?; // unknown protocol
// after
let uri: Uri = "/data/quickwit".parse()?; // bare path for local storage

const SUPPORTED_SCHEMES: [&str; 9] = ["http", "https", "grpc", "actor", "pg", "postgres", "postgresql", "ram", "s3"];
fn check_uri_scheme(uri: &str) -> Result<(), String> {
    if let Some((scheme, _)) = uri.split_once("://") {
        if !SUPPORTED_SCHEMES.contains(&scheme.to_ascii_lowercase().as_str()) {
            return Err(format!(
                "unsupported scheme '{scheme}'; use s3://, gs://, ram://, pg://, grpc://, actor://, or a plain local path"
            ));
        }
    } // no scheme => local path, OK
    Ok(())
}

match uri_str.parse::<quickwit_common::uri::Uri>() {
    Ok(uri) => use_uri(uri),
    Err(e) if e.to_string().contains("unknown URI protocol") => {
        // surface supported schemes to the user, fix config
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: Parsing a URI whose scheme is not in the supported set — e.g. `"file:///data"`, `"azure://..."`, `"s3a://bucket/x"`, `"PSQL://..."` (uppercase without normalization upstream) — via `Protocol::from_str` or `Uri::from_str` on index/storage URIs in configs and metastore records.

Common situations: Configuring an index_uri with an unsupported backend (azure without the feature/scheme, `file://` instead of a bare path), typos like `s3x://` or `gsx://`, copy-pasted URIs from other systems, or legacy configs using schemes renamed in newer Quickwit versions.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• URI `{uri}` is not a valid file URI
• {} contains invalid label format: {}
• `append_records` should be called with `position_opt: None`
• failed to run mrecordlog operation
• stdin cannot be checkpointed

AI-assisted analysis of quickwit-oss/quickwit@a39730c5cd (2026-09-08). Data as JSON: /api/errors/6134b24cd73ceebd. Report an issue: GitHub.