zeroclaw-labs/zeroclaw · error

jira.base_url must not be empty when jira.enabled = true

Error message

jira.base_url must not be empty when jira.enabled = true

What it means

Thrown by Config::validate when jira.enabled = true but jira.base_url is empty after trimming. The Jira integration resolves every API endpoint (tickets, search, transitions) relative to this base URL, so an enabled integration without a host is a hard configuration error. Validation stops before any network activity. The same block subsequently requires an api token and validates allowed_actions.

Source

Thrown at crates/zeroclaw-config/src/schema.rs:22065

            }
        }

        // Pinggy tunnel region — validate allowed values (case-insensitive, auto-lowercased at runtime).
        if let Some(ref pinggy) = self.tunnel.pinggy
            && let Some(ref region) = pinggy.region
        {
            let r = region.trim().to_ascii_lowercase();
            if !r.is_empty() && !matches!(r.as_str(), "us" | "eu" | "ap" | "br" | "au") {
                anyhow::bail!(
                    "tunnel.pinggy.region must be one of: us, eu, ap, br, au (or omitted for auto)"
                );
            }
        }

        // Jira
        if self.jira.enabled {
            if self.jira.base_url.trim().is_empty() {
                anyhow::bail!("jira.base_url must not be empty when jira.enabled = true");
            }
            if self.jira.api_token.trim().is_empty()
                && std::env::var("JIRA_API_TOKEN")
                    .unwrap_or_default()
                    .trim()
                    .is_empty()
            {
                anyhow::bail!(
                    "jira.api_token must be set (or JIRA_API_TOKEN env var) when jira.enabled = true"
                );
            }
            let valid_actions = [
                "get_ticket",
                "search_tickets",
                "comment_ticket",
                "list_projects",
                "myself",
                "list_transitions",

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Set jira.base_url to the Jira instance root, e.g. "https://yourcompany.atlassian.net" (no trailing /rest path needed)
2. Or set jira.enabled = false until the instance URL is known
3. Verify the URL scheme is https and the host resolves, to avoid the next failure being at request time

Example fix

# before
[jira]
enabled = true
base_url = ""

# after
[jira]
enabled = true
base_url = "https://yourcompany.atlassian.net"

fn jira_base_url_ok(j: &JiraConfig) -> bool {
    !j.enabled || !j.base_url.trim().is_empty()
}

match cfg.validate() {
    Err(e) if e.to_string().starts_with("jira.base_url") => {
        eprintln!("Set [jira] base_url (e.g. https://yourcompany.atlassian.net) or disable jira");
    }
    other => other?,
}

When it happens

Trigger: Setting `jira.enabled = true` with no `base_url`, an empty string, or whitespace; enabling Jira while intending to fill the URL in later; a config templating step that drops the field.

Common situations: User enables Jira before deciding which instance (company Atlassian cloud vs self-hosted Jira Server) it targets; base_url held in an env var in the user's head but never written to config; copy-paste from docs example that commented the field out.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• notion.database_id must not be empty when notion.enabled = t
• google_workspace.allowed_operations[{i}].resource must not b
• jira.api_token must be set (or JIRA_API_TOKEN env var) when
• jira.allowed_actions contains unknown action: '{}'. Valid: g
• matrix: `homeserver` is required

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/29824e6360b5e6f4. Report an issue: GitHub.