Typesense config missing (set FLOW_TYPESENSE_URL or pass --u

Error message

Typesense config missing (set FLOW_TYPESENSE_URL or pass --url)

What it means

run_index requires a Typesense configuration (URL) to query the search index. typesense_config_with_overrides combines the FLOW_TYPESENSE_URL environment variable with CLI --url overrides; if neither yields a usable config, the command bails with this message telling the user exactly which env var or flag to set.

Source

Thrown at src/install.rs:126

                "install failed after trying auto backends:\n- {}",
                errors.join("\n- ")
            );
        }
    }
}

fn is_existing_destination_error(err: &anyhow::Error) -> bool {
    err.to_string().contains("already exists")
}

fn looks_like_remote_external_cli_id(name: &str) -> bool {
    name.starts_with("cli_") || name.starts_with("cli:")
}

pub fn run_index(opts: InstallIndexOpts) -> Result<()> {
    let flox_bin = resolve_flox_bin()?;
    let Some(config) = typesense_config_with_overrides(&opts) else {
        bail!("Typesense config missing (set FLOW_TYPESENSE_URL or pass --url)");
    };

    let queries = load_index_queries(opts.query, opts.queries)?;
    if queries.is_empty() {
        bail!("no queries provided");
    }

    let mut all_entries: HashMap<String, FloxDisplayEntry> = HashMap::new();
    for query in queries {
        let results = flox_search_with_aliases(&flox_bin, &query)?;
        for entry in results {
            all_entries.entry(entry.pkg_path.clone()).or_insert(entry);
        }
    }

    if all_entries.is_empty() {
        println!("No results to index.");
        return Ok(());

View on GitHub (pinned to a747e741ae)

Solutions

Export FLOW_TYPESENSE_URL=<your-typesense-url> before running the command.
Pass --url <your-typesense-url> directly on the index subcommand invocation.
Add the env var to your shell profile/CI secrets so it is present in future runs.
Verify the variable name spelling and that it is exported, not just set locally.

Example fix

// before
f install index --query rust
// after
export FLOW_TYPESENSE_URL=http://localhost:8108
f install index --query rust

Defensive patterns

Strategy: validation

Validate before calling

fn typesense_ready() -> bool {
    std::env::var("FLOW_TYPESENSE_URL")
        .map(|v| !v.trim().is_empty())
        .unwrap_or(false)
}
if !typesense_ready() {
    eprintln!("set FLOW_TYPESENSE_URL or pass --url before indexing");
}

Try / catch

match run_index(opts) {
    Err(e) if e.to_string().contains("Typesense config missing") => {
        eprintln!("export FLOW_TYPESENSE_URL=... or re-run with --url <typesense-url>");
    }
    r => r?,
}

Prevention

Export FLOW_TYPESENSE_URL in shell profiles and CI secrets
Prefer the explicit --url flag in scripts so they are self-contained
Check env var spelling/case and that it is exported, not just set

When it happens

Trigger: Running the index subcommand without FLOW_TYPESENSE_URL set in the environment and without passing --url on the command line.

Common situations: Fresh machine/CI where the env var was never exported; typo'd variable name (wrong case or prefix); running from a shell that didn't source the profile exporting the variable.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/fdb14f18e0856ecd. Report an issue: GitHub.