vercel/turborepo · warning

skipping automatic task caching - file accessed outside of r

Error message

skipping automatic task caching - file accessed outside of repo root ({unescaped_str})

What it means

In automatic (traced) caching mode, TaskAccess::can_cache (crates/turborepo-lib/src/run/task_access.rs:106-121) checks every file path the task accessed; a path whose relation to the repo root is Parent or Divergent (i.e. outside the repository) makes the task non-cacheable, since cache replay cannot reproduce external file state. The offending path is included in the message.

Source

Thrown at crates/turborepo-lib/src/run/task_access.rs:114

    pub fn can_cache(&self, repo_root: &AbsoluteSystemPathBuf) -> bool {
        // network
        if self.accessed.network {
            turborepo_log::warn(
                turborepo_log::Source::turbo(turborepo_log::Subsystem::TaskAccess),
                "skipping automatic task caching - detected network access",
            )
            .emit();
            return false;
        }

        // file system
        for unescaped_str in &self.accessed.file_paths {
            match AbsoluteSystemPathBuf::new(unescaped_str.to_string()) {
                Ok(path) => {
                    let relation = path.relation_to_path(repo_root);
                    // only paths within the repo can be automatically cached
                    if relation == PathRelation::Parent || relation == PathRelation::Divergent {
                        turborepo_log::warn(
                            turborepo_log::Source::turbo(turborepo_log::Subsystem::TaskAccess),
                            format!(
                                "skipping automatic task caching - file accessed outside of repo \
                                 root ({unescaped_str})"
                            ),
                        )
                        .emit();
                        return false;
                    }
                }
                Err(e) => {
                    debug!("failed to parse path {unescaped_str}: {e}");
                }
            }
        }

        for output in &self.outputs {
            let output = output.strip_prefix('!').unwrap_or(output.as_str());

View on GitHub (pinned to f9245100cf)

Solutions

1. Identify the reported path and make the task read an in-repo copy instead (commit config, vendor the dependency, or generate it in an earlier cached task).
2. Give the task explicit inputs/outputs in turbo.json so caching is declared rather than inferred from the trace.
3. Fix symlinks that escape the repo (hoisted/external node_modules) so all accessed files resolve inside the workspace.
4. Set env/config so tools use in-repo caches (e.g. npm_config_cache=.npm-cache inside the package).

Example fix

# before: script reads config above the repo
import conf from '../../../shared-config.json'   # -> file accessed outside of repo root

# after: keep the dependency inside the workspace
import conf from '../../shared-config.json'   # or declare it as an explicit input

#!/usr/bin/env bash
# detect repo-escaping file references before running with auto-caching
ROOT=$(git rev-parse --show-toplevel)
grep -rnE "(\.\./){2,}|(^|['\"])/(etc|usr|home|Users)/" \
  --include=package.json --include=*.config.* "$ROOT/packages" \
  && echo "review paths outside repo root — auto-caching will skip these tasks" >&2
# exit 0 intentionally; this is advisory

When it happens

Trigger: The task's access trace contains absolute paths resolving above the repo root or on another tree — e.g. reads from ~/.config, /etc, /usr/lib/node_modules, a sibling checkout, or a symlink escaping the repo. AbsoluteSystemPathBuf::new succeeds for these, relation_to_path classifies them Parent/Divergent, and can_cache returns false.

Common situations: Tools reading user-level config or caches (~/.npm, ~/.cache, ~/Library), monorepos referencing sibling projects via ../, symlinked node_modules pointing outside the workspace, and containerized builds touching host paths.

Related errors

• skipping automatic task caching - detected network access
• error creating log file directory: {err:?}
• error creating log file: {err:?}
• skipping automatic task caching - output generated outside o
• Error writing run summary: {err}

AI-assisted analysis of vercel/turborepo@f9245100cf (2026-08-17). Data as JSON: /api/errors/f82f0893655dcf26. Report an issue: GitHub.