{"record":{"id":"93ba442ecfdbf6c7","repo":"gastownhall/beads","slug":"jira-url-not-configured-set-jira-url-or-jira-url","errorCode":null,"errorMessage":"Jira URL not configured (set jira.url or JIRA_URL)","messagePattern":"Jira URL not configured \\(set jira\\.url or JIRA_URL\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/jira/tracker.go","lineNumber":66,"sourceCode":"\n// PrimaryProjectKey returns the first configured project key.\nfunc (t *Tracker) PrimaryProjectKey() string {\n\tif len(t.projectKeys) == 0 {\n\t\treturn \"\"\n\t}\n\treturn t.projectKeys[0]\n}\n\nfunc (t *Tracker) Name() string         { return \"jira\" }\nfunc (t *Tracker) DisplayName() string  { return \"Jira\" }\nfunc (t *Tracker) ConfigPrefix() string { return \"jira\" }\n\nfunc (t *Tracker) Init(ctx context.Context, store storage.Storage) error {\n\tt.store = store\n\n\tjiraURL, err := t.getConfig(ctx, \"jira.url\", \"JIRA_URL\")\n\tif err != nil || jiraURL == \"\" {\n\t\treturn fmt.Errorf(\"Jira URL not configured (set jira.url or JIRA_URL)\")\n\t}\n\tt.jiraURL = jiraURL\n\n\t// Resolve project keys: use pre-set keys (from CLI), or fall back to config.\n\tif len(t.projectKeys) == 0 {\n\t\tpluralVal, _ := t.getConfig(ctx, \"jira.projects\", \"JIRA_PROJECTS\")\n\t\tsingularVal, _ := t.getConfig(ctx, \"jira.project\", \"JIRA_PROJECT\")\n\t\tt.projectKeys = tracker.ResolveProjectIDs(nil, pluralVal, singularVal)\n\t}\n\tif len(t.projectKeys) == 0 {\n\t\treturn fmt.Errorf(\"Jira project not configured (set jira.project, jira.projects, or JIRA_PROJECT)\")\n\t}\n\n\tusername, _ := t.getConfig(ctx, \"jira.username\", \"JIRA_USERNAME\")\n\tapiToken, err := t.getConfig(ctx, \"jira.api_token\", \"JIRA_API_TOKEN\")\n\tif err != nil || apiToken == \"\" {\n\t\treturn fmt.Errorf(\"Jira API token not configured (set jira.api_token or JIRA_API_TOKEN)\")\n\t}","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/jira/tracker.go#L48-L84","documentation":"Tracker.Init validates configuration before constructing the Jira client, and the first mandatory value is the Jira instance base URL. It reads config key 'jira.url' and falls back to env var JIRA_URL; if the config lookup errors or yields an empty string, Init fails fast with this message naming both sources. No network calls have happened yet.","triggerScenarios":"Init(ctx, store) is called with neither the 'jira.url' config entry present nor the JIRA_URL environment variable set (or getConfig errors).","commonSituations":"Fresh install where config was never initialized; running in a container/scheduler that does not pass JIRA_URL through; typo'd env var name (JIRAURL, JIRA_HOST); config file present but loaded into the wrong storage/profile.","solutions":["Set the JIRA_URL environment variable (e.g. export JIRA_URL=https://yourorg.atlassian.net).","Or set the 'jira.url' key in the tracker config store.","Verify the process environment actually contains the var (print env in the same context where the tracker runs).","Check spelling/case of the env var and that secrets/config are mounted in CI/container environments.","Re-run init and confirm subsequent required values (project, token) are also present to avoid the next failure in the chain."],"exampleFix":"// before: nothing set\ntracker.Init(ctx, store) // → error\n// after\nos.Setenv(\"JIRA_URL\", \"https://yourorg.atlassian.net\")\nerr := tracker.Init(ctx, store)","handlingStrategy":"validation","validationCode":"func requireEnv(keys ...string) error {\n    for _, k := range keys {\n        if os.Getenv(k) == \"\" {\n            return fmt.Errorf(\"missing required env var %s\", k)\n        }\n    }\n    return nil\n}\n// usage: requireEnv(\"JIRA_URL\") before tracker.Init","typeGuard":null,"tryCatchPattern":"if err := tracker.Init(ctx, store); err != nil {\n    if strings.Contains(err.Error(), \"Jira URL not configured\") {\n        return fmt.Errorf(\"setup incomplete: export JIRA_URL=https://yourorg.atlassian.net\")\n    }\n    return err\n}","preventionTips":["Set JIRA_URL (or jira.url) in every environment the tracker runs in (local, CI, containers).","Validate all Jira env vars in a startup script before invoking the app.","Ensure .env files are loaded and secrets are mounted in containerized runs.","Use exact variable names; document them in your project's setup README.","Fail fast with a config check command in CI pipelines."],"tags":["jira","configuration","environment","bootstrap"],"backgroundTag":"missing-env-var","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}