{"record":{"id":"83c6f244b703bcf3","repo":"windmill-labs/windmill","slug":"base-internal-url-is-required-in-agent-mode","errorCode":null,"errorMessage":"BASE_INTERNAL_URL is required in agent mode","messagePattern":"BASE_INTERNAL_URL is required in agent mode","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"backend/windmill-common/src/utils.rs","lineNumber":125,"sourceCode":"    pub static ref MODE_AND_ADDONS: ModeAndAddons = {\n        let mut search_addon = false;\n        let mode = std::env::var(\"MODE\")\n        .map(|x| x.to_lowercase())\n        .map(|x| {\n            if &x == \"server\" {\n                println!(\"Binary is in 'server' mode\");\n                Mode::Server\n            } else if &x == \"worker\" {\n                tracing::info!(\"Binary is in 'worker' mode\");\n                #[cfg(windows)]\n                {\n                    println!(\"It is highly recommended to use the agent mode instead on windows (MODE=agent) and to pass a BASE_INTERNAL_URL\");\n                }\n                Mode::Worker\n            } else if &x == \"agent\" {\n                println!(\"Binary is in 'agent' mode with BASE_INTERNAL_URL={}\", std::env::var(\"BASE_INTERNAL_URL\").unwrap_or_default());\n                if std::env::var(\"BASE_INTERNAL_URL\").is_err() {\n                    panic!(\"BASE_INTERNAL_URL is required in agent mode\")\n                }\n                if std::env::var(\"AGENT_TOKEN\").is_err() {\n                    println!(\"AGENT_TOKEN is not passed. This is required for the agent to work and contains the JWT to authenticate with the server.\")\n                }\n\n                #[cfg(not(feature = \"enterprise\"))]\n                {\n                    panic!(\"Agent mode is only available in the EE, ignoring...\");\n                }\n                #[cfg(feature = \"enterprise\")]\n                Mode::Agent\n            } else if &x == \"indexer\" {\n                tracing::info!(\"Binary is in 'indexer' mode\");\n                #[cfg(not(feature = \"tantivy\"))]\n                {\n                    eprintln!(\"Cannot start the indexer because tantivy is not included in this binary/image. Make sure you are using the EE image if you want to access the full text search features.\");\n                    panic!(\"Indexer mode requires compiling with the tantivy feature flag.\");\n                }","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/windmill-labs/windmill/blob/e474e8803ce2ff5c2df09a58dab51d45f5c922ca/backend/windmill-common/src/utils.rs#L107-L143","documentation":"In agent mode the binary acts as a remote agent that calls back to a Windmill server, so it must know the server's internally reachable address. `Mode` parsing in windmill-common panics when `MODE=agent` is set but `BASE_INTERNAL_URL` is unset — the agent cannot function without knowing where to reach the server.","triggerScenarios":"Starting the binary with `MODE=agent` and no `BASE_INTERNAL_URL` environment variable defined.","commonSituations":"Deploying agents in EE setups and forgetting the env var; copying worker config to an agent without adding BASE_INTERNAL_URL; URL set only in a compose file that the agent container doesn't inherit.","solutions":["Set BASE_INTERNAL_URL to the server's address reachable from the agent (e.g. https://windmill.example.com)","Also set AGENT_TOKEN — it is required for authentication and only warns if missing, but the agent will not work without it","If you only need a worker and not an agent, use MODE=worker instead"],"exampleFix":"// before\nMODE=agent\n// after\nMODE=agent\nBASE_INTERNAL_URL=https://windmill.example.com\nAGENT_TOKEN=<jwt>","handlingStrategy":"validation","validationCode":"# preflight before launching in agent mode\nif [ \"$MODE\" = \"agent\" ]; then\n  [ -n \"$BASE_INTERNAL_URL\" ] || { echo \"agent mode requires BASE_INTERNAL_URL\" >&2; exit 1; }\n  [ -n \"$AGENT_TOKEN\" ] || { echo \"agent mode requires AGENT_TOKEN\" >&2; exit 1; }\n  curl -fsS \"$BASE_INTERNAL_URL/api/health\" >/dev/null || { echo 'BASE_INTERNAL_URL unreachable'; exit 1; }\nfi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Template BASE_INTERNAL_URL and AGENT_TOKEN into every agent deployment manifest","Smoke-test server reachability from the agent network before rollout","Document that agents also need AGENT_TOKEN even though its absence only warns"],"tags":["configuration","env-var","agent","startup"],"backgroundTag":"missing-env-var","analyzedSha":"e474e8803ce2ff5c2df09a58dab51d45f5c922ca","analyzedAt":"2026-09-03T12:38:19.024Z","contentChangedAt":"2026-09-03T12:38:19.024Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}