Troubleshooting¶
Start Here — envoy --diagnose¶
Before digging into a specific symptom below, run:
en --diagnose # bundles, team/stack, cache, VCS, telemetry status
en --diagnose python # also shows the command's full resolved environment
This surfaces discovered bundles and commands, resolved team/stack context, bundle cache location and state (with how each bundle stands with it), detected VCS backend, and bundle-root reachability (flagging unreachable network paths) in one report — often enough to spot the problem before checking the more specific sections below.
A Bundle Is Not Being Cached, or the Cache Misbehaves¶
en --diagnose shows beside each bundle whether it is [cached],
[not cached yet], [refused: ...] or [never cached: ...], and why.
en cache status shows where the cache is and whether caching is on, and on
Windows whether long paths are on.
| What you see | What it means |
|---|---|
[never cached: it has no .bundle marker ...] |
The bundle was copied to the share by hand. Publish it with engit publish bundle, which writes the marker |
[refused: ... would reach N characters ...] |
A path in the bundle is too long for the cache directory: for Windows, or for the lower limit an administrator set with ENVOY_CACHE_MAX_PATH (the message says when that set it). Choose a shorter directory with ENVOY_CACHE_ROOT (or --cache-root), publish the bundle with shorter paths, or ask an administrator to turn on Windows long paths or to raise the cap (see Long paths on Windows); en cache status says whether long paths are on and shows the cap while one is set |
Bundle caching is unavailable warning |
The cache directory cannot be created or written, for example because it is read-only. Envoy runs from the share meanwhile; point ENVOY_CACHE_ROOT somewhere writable |
Could not cache ... not enough free space |
The drive holding the cache is full. en cache list shows what is using it; en cache prune or en cache clear frees it, and ENVOY_CACHE_MAX_SIZE keeps it bounded |
| The first run of a command is slow | Expected: bundles are copied once. Warm a machine ahead of time with en --noop |
| A cached bundle misbehaves | en cache verify checks each entry is complete. Delete a damaged entry's directory, or run en cache clear; envoy copies it again |
| You want to bypass the cache once | en --cache off <command> runs from the share and copies nothing |
warning: this directory is on a network location |
The cache directory is on a network location, where a cache saves little and file locks can be unreliable (often a home directory mounted over NFS). Point ENVOY_CACHE_ROOT at a local disk |
See Bundle Caching for the whole picture.
The Share Is Unreachable¶
A stack that has run on this machine with caching on starts without its share,
from the bundles in the local cache (how).
en --diagnose shows from a snapshot under the stack when that is what happened.
| What you see | What it means |
|---|---|
envoy: the stack root ... cannot be reached; using stack 'studio' (...) as it was 3 hours ago |
Not an error. The share is down, so envoy used the stack as it was the last time a command ran with the share reachable. It is refreshed on the next run once the share is back |
envoy: not cached on this machine, so unavailable: ext:pyside@... |
The stack lists bundles that were never copied here, so the commands that need them are missing until the share is back. Prepare a laptop beforehand with en -s=studio --noop |
Named stack "studio" not found in ENVOY_STACK_ROOTS (the stack root ... cannot be reached), and no earlier run of it is remembered on this machine |
This machine has not run that stack with caching on, or the stack has no published bundle (nothing is remembered for one), so it needs the share. A stack that was selected by path says Stack path does not exist: ... in the same place. Check the name against en --list-stacks |
... none of its bundles are cached on this machine (...) |
The stack ran here, but nothing of it is in the cache, because the commands that ran needed no published bundle, or the cache was cleared. It needs the share once more |
Named stack "studio" not found in ENVOY_STACK_ROOTS with no "cannot be reached" |
The share is reachable and does not publish that name. en --list-stacks shows what it does publish |
... (the stack root ... cannot be reached) after an error with caching off |
ENVOY_CACHE=off (or --cache off) stops envoy using a remembered stack, so the share is needed |
envoy: ENVOY_STACK_CONTEXT selects a stack from ENVOY_STACK_ROOTS, but ... cannot be reached, so no stack was selected |
A context is resolved by searching the stack roots, so it cannot start without them. The note ends with the stacks remembered from earlier runs (a stack chosen by context is remembered under its name); start one with en --stack <name>. With none listed, nothing has run here with caching on |
I/O error at ...studio.estack: Access is denied while the share is up |
The share answered and refused the file, so this is a permissions or publishing mistake, not an outage. Envoy does not run a remembered copy instead, because that would hide it. Ask whoever published the stack to fix its permissions |
The Launcher Will Not Start Envoy¶
envoy --envoy-shim-resolve shows which version you are pinned to, where the
redirect file came from, and whether that version is cached. The launcher's own
failures are one line starting envoy: and use exit codes 64, 69, 70 and
78 (see the launcher).
| What you see | What it means |
|---|---|
no redirect file is configured. Set ENVOY_CONFIG_PROD ... (78) |
Set ENVOY_CONFIG_PROD to the team's config folder, or ENVOY_REDIRECT_CONFIG to a redirect file |
the redirect file could not be used, and there is no saved copy ... (78) |
The file is missing, unreadable, or invalid, and this machine has never read a good one. The message lists each place tried and why. Check that the share is reachable and that redirect.yaml is in the folder ENVOY_CONFIG_PROD names |
the redirect file could not be used (...); using the copy saved 3 hours ago |
Not an error. The share was unreachable, or the file on it is invalid or too new for this launcher (the message says which), so the launcher used the last good copy it saved. The administrator can check the file with --envoy-shim-validate-config |
envoy v0.8.0 is not cached and could not be found (looked in: ...) (69) |
The version is not on this machine and not on any source. The message says why each source was no good: an unset ${VAR}, or no bin/envoy in the folder. Ask the administrator to publish it, or check that the share is reachable |
'alice' is assigned to group 'x', which has no version (78) |
The redirect file names a group under users that has no entry under versions |
the redirect file has no 'default' version, and 'bob' has no assignment (78) |
Users who are not listed need a default version; add one |
the redirect file uses schema 2, but this envoy understands up to schema 1 |
The file is newer than this launcher. Update the launcher: envoy --envoy-shim-update, or run the installer again. Until then it uses its saved copy of the file |
envoy: could not cache envoy v0.8.0 (...); running it from ... |
The local copy failed (disk full, directory not writable). It still ran, from the share. Fix the cache directory (see above) |
| The wrong version runs | --envoy-shim-resolve says which version and why. Check for ENVOY_VERSION, and for ENVOY_BIN_LOCK: a program that envoy started stays on the version that started it |
An old envoy runs instead of the launcher |
An older install comes first on PATH. Get-Command envoy -All (PowerShell) or which -a envoy shows the order |
The launcher did not update after current.json changed |
Installed launchers look once a day. envoy --envoy-shim-update looks now. A launcher run from a checkout, or installed machine-wide, never updates itself, and ENVOY_SHIM_UPDATE=off stops it |
Set ENVOY_VERSION=<version> to run a particular version for one session
without touching the redirect file.
"Could not find commands.json"¶
Envoy has no commands to load. Fix one of:
- Set
ENVOY_BNDL_ROOTSto point to a directory containing bundle subdirectories - Use
--stack/-swith a path to astudio.estack - Use
--commands-file/-cwith a direct path tocommands.json - Run from inside a project that has
.envoy/commands.json
Commands Not Appearing in --list¶
Check the verbose output for:
- Which roots are being scanned
- Which directories have
.git/but no.envoy/(or vice versa) - Any parse errors in
commands.json
Common causes:
| Symptom | Likely cause |
|---|---|
| Root scanned, no bundles found | Bundles are not direct children of the root (scan is one level deep) |
| Bundle found but no commands | commands.json missing, empty, or has a JSON syntax error |
| Bundle not found at all | .git/ directory missing (required for auto-discovery) |
| Command from wrong bundle | Command conflict — last bundle wins; check with --verbose |
Executable Not Found¶
In closed mode the subprocess PATH comes entirely from bundle env files. If the executable is not found:
- Ensure the bundle env file sets
+=PATHpointing to the executable's directory - Use
en --which <command>to see what path resolves against the subprocessPATH - Use
en -i <command>temporarily to confirm the executable is present on the systemPATH
Environment Variables Not Applying¶
- Check JSON syntax in env files — use a JSON linter
- Run
en --verbose <command>to see exactly which files are loaded and what values are set - In closed mode,
${VARNAME}references to system variables expand to empty string unless the variable is inENVOY_ALLOWLISTor is a core OS variable - Use
en --trace VAR <command>to see how a specific variable is mutated across files
Path Inconsistency (Mixed Slashes)¶
Envoy normalizes all env file values to OS-native separators before applying them. If you see mixed slashes in a subprocess, the value likely came directly from the system environment (via ENVOY_ALLOWLIST or --inherit-env) rather than from a bundle env file.
Set the variable explicitly in an env file to ensure normalization is applied:
Null/Unresolved Variable Warnings¶
WARNING: Variable 'SITE_PACKAGES' is null in python_env.json — skipping.
WARNING: List item '${ENVOY_SITE_PACKAGES}' in 'PYTHONPATH' (python_env.json)
contains unresolved references: ENVOY_SITE_PACKAGES — skipping item.
These warnings are informational — they indicate a variable or list item was intentionally or accidentally left undefined. To suppress:
- Remove the entry from the JSON file if not needed
- Set the variable before it is referenced (earlier env file,
global_env.json, orENVOY_ALLOWLIST) - Use
?=to make the value conditional instead of referencing an undefined variable
Envoy Utils Issues¶
Troubleshooting for engit is maintained with
Envoy Utils.