Which ShotGrid Toolkit root path definitions cause local success but production failure?

Question

Problem Context
The ShotGrid Toolkit is often configured on a developer’s workstation with absolute or OS‑specific paths in the roots section of templates.yml or the site preferences. Those paths resolve correctly on the local machine but may not exist or be mounted on production render farms or other OSes.
Unresolved Decision
When the same configuration is deployed to a distributed environment, users receive a cached copy of the YAML files. If a root path is missing or mismatched on a production host, the Toolkit bootstrap silently falls back to a default or an alternate environment, leading to silent failures or incorrect asset resolution.
Goal
Identify a configuration strategy that guarantees consistent root path resolution across both local development and production render environments, accounting for OS differences and distributed cache behavior.
Questions

Which root path definitions should be used to guarantee consistent resolution across local and production environments?
How can we detect mismatched root definitions before deployment?
What testing strategy ensures that a distributed configuration receives updated root definitions after a change?

Tasadduq Burney · Answer

Direct answer
Root path definitions that cause local success but production failure are those that lack an OS‑specific key for the farm OS, use absolute per‑user or drive‑letter paths, or rely on mount points that exist only on the workstation.
Confirmed facts

roots are defined in config/core/templates.yml under a roots: mapping.
Each named root may contain windows_path, linux_path, mac_path keys.
If the key for the current OS is missing or points to a non‑existent mount, the Toolkit cannot resolve {root_name} tokens and falls back to a cached default, producing silent failures.

Likely explanation
On a developer workstation the configuration often includes only the OS‑specific key that matches the workstation (e.g., only windows_path) or uses absolute per‑user paths such as C:\Users\dev\projects or /Users/dev/Projects. Those paths exist locally but are absent or have different case on Linux render‑farm nodes, so the same YAML resolves correctly on the workstation but fails on the farm.
Steps to verify and fix

Inspect templates.yml for any root that lacks a key for the OS used on the farm (e.g., missing linux_path when farm nodes run Linux).
Replace per‑user or drive‑letter paths with OS‑agnostic, farm‑visible mount points (e.g., /mnt/shared/projects on Linux, Z:\projects on Windows, /Volumes/shared/projects on macOS) and provide the same path under all three OS keys.
Ensure the casing of the mount point matches exactly what the farm sees (Linux is case‑sensitive).
Run a validation check on a node of each OS:
# Example using the Tank CLI (adjust for your core version)
tank validate
# Or a quick sgtk script:
python -c "import sgtk; tk = sgtk.sgtk_from_path('.'); print(tk.template_root('primary'))"

If any root resolves to a non‑existent path or returns None, the definition is problematic.
After fixing, bump the descriptor version in config/core/install_location.yml (or equivalent) and publish a new configuration version so cached copies on the farm are refreshed.

Missing diagnostic detail
If you are unsure whether your farm nodes are Linux‑only, Windows‑only, or mixed, let me know which OS keys are required; that determines whether you need to define windows_path, linux_path, and/or mac_path for each root.

Which ShotGrid Toolkit root path definitions cause local success but production failure?

Problem Context

Unresolved Decision

Goal

Questions

1 answer

Direct answer

Confirmed facts

Likely explanation

Steps to verify and fix

Missing diagnostic detail

Your perspective belongs here.

0 question comments