{"record":{"id":"459a9539dbcda23f","repo":"astral-sh/ruff","slug":"invalid-cache-dir-value-e","errorCode":null,"errorMessage":"Invalid `cache-dir` value: {e}","messagePattern":"Invalid `cache-dir` value: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/ruff_workspace/src/configuration.rs","lineNumber":554,"sourceCode":"            lint.common = lint.common.combine(options.lint_top_level.0);\n            lint\n        } else {\n            LintOptions {\n                common: options.lint_top_level.0,\n                ..LintOptions::default()\n            }\n        };\n\n        Ok(Self {\n            builtins: options.builtins,\n            cache_dir: options\n                .cache_dir\n                .map(|dir| {\n                    let dir = shellexpand::full(&dir);\n                    dir.map(|dir| fs::normalize_path_to(dir.as_ref(), project_root))\n                })\n                .transpose()\n                .map_err(|e| anyhow!(\"Invalid `cache-dir` value: {e}\"))?,\n\n            exclude: options.exclude.map(|paths| {\n                paths\n                    .into_iter()\n                    .map(|pattern| {\n                        let absolute = GlobPath::normalize(&pattern, project_root);\n                        FilePattern::User(pattern, absolute)\n                    })\n                    .collect()\n            }),\n            extend: options\n                .extend\n                .map(|extend| {\n                    let extend = shellexpand::full(&extend);\n                    extend.map(|extend| PathBuf::from(extend.as_ref()))\n                })\n                .transpose()\n                .map_err(|e| anyhow!(\"Invalid `extend` value: {e}\"))?,","sourceCodeStart":536,"sourceCodeEnd":572,"githubUrl":"https://github.com/astral-sh/ruff/blob/26f38c119cac42e4d320ba08f09224fdec74af2c/crates/ruff_workspace/src/configuration.rs#L536-L572","documentation":"Ruff expands environment/user variables (via shellexpand) in the configured `cache-dir` setting. If the value contains an undefined variable or malformed syntax (e.g. `$UNSET_VAR` or a bad `${...}` form), expansion fails and configuration loading aborts with this error.","triggerScenarios":"pyproject.toml/ruff.toml sets `cache-dir` referencing an environment variable that is not set, or containing invalid expansion syntax that shellexpand::full rejects.","commonSituations":"CI environments where the variable is defined locally but not exported, typos in variable names, copying configs between machines, or values like `~/$PROJECT/.ruff_cache` where $PROJECT is unset.","solutions":["Set the referenced environment variable in the environment running Ruff (export it in CI/shell profile).","Replace the variable in `cache-dir` with a literal path, e.g. cache-dir = \".ruff_cache\".","Escape a literal dollar sign as `$$` if you actually want a $ in the path.","Validate the config with `ruff check --no-cache` or `ruff config` to isolate the bad value."],"exampleFix":"# before (pyproject.toml)\n[tool.ruff]\ncache-dir = \"$XDG_CACHE_HOME/ruff\"  # XDG_CACHE_HOME unset\n# after\n[tool.ruff]\ncache-dir = \".ruff_cache\"","handlingStrategy":"validation","validationCode":"import os, re\nval = \"$(grep -oP 'cache-dir\\\\s*=\\\\s*\"\\K[^\"]+' pyproject.toml)\"\nfor var in re.findall(r'\\$(\\w+)|\\$\\{(\\w+)\\}', val):\n    name = var[0] or var[1]\n    assert name in os.environ, f\"environment variable {name} referenced in cache-dir is not set\"","typeGuard":null,"tryCatchPattern":"// CI step: fail fast before running ruff\n- run: |\n    if grep -q 'cache-dir.*\\$' pyproject.toml; then\n      grep -oP 'cache-dir\\s*=\\s*\"\\K[^$]+(?=\\$)' pyproject.toml | while read v; do\n        [ -n \"${!v+x}\" ] || { echo \"Missing env var $v for cache-dir\"; exit 1; }\n      done\n    fi\n- run: ruff check .","preventionTips":["Export all variables referenced by cache-dir in CI and shell profiles.","Prefer literal relative paths over variable expansion in cache-dir.","Escape literal dollar signs as $$ in the config value.","Validate config on a fresh machine/CI runner before relying on it."],"tags":["ruff","configuration","env-var","cache-dir"],"backgroundTag":"env-var-expansion-failed","analyzedSha":"26f38c119cac42e4d320ba08f09224fdec74af2c","analyzedAt":"2026-09-05T10:32:37.492Z","contentChangedAt":"2026-09-05T10:32:37.492Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}