{"record":{"id":"b9b76fe7d863e763","repo":"nikivdev/code","slug":"docs-exists-but-is-a-file","errorCode":null,"errorMessage":"docs/ exists but is a file: {}","messagePattern":"docs/ exists but is a file: (.+?)","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"src/docs.rs","lineNumber":355,"sourceCode":"        Some(path) => {\n            let raw = path.to_string_lossy();\n            let expanded = config::expand_path(&raw);\n            if expanded.is_absolute() {\n                expanded\n            } else {\n                cwd.join(expanded)\n            }\n        }\n        None => project_root.to_path_buf(),\n    };\n    create_docs_scaffold_at(&target_root, opts.force)\n}\n\npub fn create_docs_scaffold_at(project_root: &Path, force: bool) -> Result<()> {\n    let docs_dir = project_root.join(PROJECT_DOCS_DIR);\n    if docs_dir.exists() {\n        if docs_dir.is_file() {\n            bail!(\"docs/ exists but is a file: {}\", docs_dir.display());\n        }\n        if !force {\n            let template_root = config::expand_path(DEFAULT_DOCS_TEMPLATE_ROOT);\n            let template_docs = template_root.join(HUB_CONTENT_ROOT);\n            if !template_docs.exists() {\n                bail!(\"Docs template not found at {}\", template_docs.display());\n            }\n            merge_docs_scaffold(&docs_dir, &template_docs)?;\n            ensure_index_file(&docs_dir, \"Docs\")?;\n            println!(\n                \"Docs already exists; merged template into {}\",\n                docs_dir.display()\n            );\n            return Ok(());\n        }\n        fs::remove_dir_all(&docs_dir)\n            .with_context(|| format!(\"failed to remove {}\", docs_dir.display()))?;\n    }","sourceCodeStart":337,"sourceCodeEnd":373,"githubUrl":"https://github.com/nikivdev/code/blob/a747e741ae92c09071d0ae946ab48488adcff1ce/src/docs.rs#L337-L373","documentation":"Raised by `create_docs_scaffold_at` (src/docs.rs:355) when the target docs directory path exists but is a regular file instead of a directory. The scaffold creation cannot merge templates into or write under a file, so it aborts naming the offending path.","triggerScenarios":"Calling `f setup`/docs scaffold creation where `PROJECT_DOCS_DIR` (docs/) resolves to a file: someone created a file named `docs` (no extension) at the project root, a bad archive/checkout materialized docs as a file, or a symlink pointing to a file.","commonSituations":"Accidental `touch docs`, a tarball extracting a `docs` file, editor tooling creating a `docs` scratch file, or leftover artifacts from a broken migration.","solutions":["Inspect the path: `ls -la` on the printed location and confirm it is a file","Move or remove the file (`mv docs docs.bak` or `rm docs`) once its contents are safe, then rerun setup","If it contains wanted content, rename it to a markdown file and rerun scaffold creation","Fix any symlink pointing docs at a regular file"],"exampleFix":"// before\n$ ls -la docs\n-rw-r--r-- docs\nerror: docs/ exists but is a file: /path/docs\n// after\nmv docs docs-notes.txt && f setup","handlingStrategy":"validation","validationCode":"let docs = Path::new(\"docs\");\nif docs.exists() && !docs.is_dir() {\n    anyhow::bail!(\"docs exists but is a file; move or remove it before setup\");\n}\nf_setup()?;","typeGuard":"fn is_dir_or_absent(p: &Path) -> bool {\n    !p.exists() || p.is_dir()\n}","tryCatchPattern":"match f_setup() {\n    Err(e) if e.to_string().contains(\"exists but is a file\") => {\n        eprintln!(\"{e:#}; rename the file and rerun setup\");\n    }\n    other => other?,\n}","preventionTips":["Never create files named `docs` at the project root","Verify archive/checkout results materialize docs as a directory","Check symlinks pointing docs at regular files","Run ls -la on the path when the error names it"],"tags":["filesystem","docs","scaffold"],"backgroundTag":"path-is-not-a-directory","analyzedSha":"a747e741ae92c09071d0ae946ab48488adcff1ce","analyzedAt":"2026-09-01T22:43:55.719Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}