Diagnose and fix the most common LATdx CLI failures.
Quick checks
Before drilling into a specific failure mode, run these to confirm the basics:
latdx --versionto confirm the binary is onPATH.latdx daemon statusto see whether a daemon is running for the current workspace.latdx cache statusto size up workspace cache and temp state.sf org listto confirm Salesforce auth and the default org alias.latdx --version -o my-orgto verify the org is reachable.
Daemon connection issues
Errors mentioning socket/connect/request timeout, or test runs that hang on daemon connect.
The CLI talks to a per-workspace daemon over a Unix socket (or named pipe on Windows). Stale sockets, crashed daemons, or a corrupted workspace cache can leave the connection wedged.
Re-run with verbose output
Capture detailed diagnostics so the next steps target the real cause:
latdx test run -n MyTest -o my-org -vCheck daemon and cache state
latdx cache statusClear daemon and cache artifacts
latdx cache clear --allRetry the original command
Org mode can still fall back to direct core execution when the daemon fails, so the run will complete either way.
Each git worktree gets its own daemon. If only one worktree misbehaves, restart that worktree’s daemon with latdx daemon restart instead of clearing every workspace.
Org readiness issues
Org alias resolution issues, or “no default org” errors.
LATdx requires an authenticated org to run org-mode tests.
Verify auth and the default org
sf org listPass an explicit org alias
latdx test run -n MyTest -o my-orgFor list mode:
latdx test list -o my-orgConfirm the org is reachable
latdx --version -o my-orgSet a default org once with sf config set target-org=my-org and you can drop -o my-org from every command.
Debug log storage exceeded
Error indicates debug log storage exceeded. Run stops before normal test results complete.
Salesforce caps ApexLog storage per org at 1 GB. Once full, no further test runs can write logs until the storage is reclaimed.
- Accept the CLI prompt to delete logs and retry when offered.
- If needed, rerun the command and confirm the cleanup prompt.
- Reduce repeated high-volume runs while diagnosing and use targeted test selection.
In non-interactive environments (the CI env var set, or non-TTY stdout) the CLI auto-deletes logs and retries instead of prompting. Set LATDX_AUTO_CONFIRM=true to force the same behavior in an interactive terminal.
Compilation and test failures
Compile problems in output, or tests fail with stack traces or class/method errors.
These usually point at real Apex defects, but can also surface adapter or execution-strategy bugs. Narrow scope and switch strategies to isolate.
Re-run with verbose output
latdx test run -n MyTest -o my-org -vIsolate execution strategy
Add --sequential to disable packed execution, or set LATDX_LATDB=off to switch from dbsim to full mode.
Narrow scope to one test method
latdx test run -t MyTest.testMethod -o my-orgVerify the file mode path contains test methods
If running in file mode, confirm the path exists and exposes Apex test methods:
latdx test list -f force-app/main/default/classes/MyTest.clsInput validation errors
Cannot use --class-names or --tests with --file or --dir
Cannot use --method with --dir or org mode
The CLI enforces one input family per run so the daemon path and the in-process file path do not clash.
- Choose exactly one input family per run:
- Org mode:
--class-namesor--tests(or no file/dir). - File mode:
--fileor--dir.
- Org mode:
- Use
--methodonly with--file.
latdx test list accepts the same input families. Use it to dry-run discovery before launching test run.
Silent auto-update didn’t run
A newer release exists but the CLI didn’t pick it up on the next invocation.
The CLI auto-installs newer releases in a detached background process after a successful command (see Automatic Background Updates). When something blocks that path, the run log is your first stop.
Check the update log
cat ~/.latdx/update.logEvery silent-update attempt appends one line per phase: start, install stdout, success, or failure (with the underlying error). Common causes: GitHub rate limiting, curl / wget missing, no write access to the install location, or the targeted release tag was deleted.
Confirm auto-update is enabled
latdx config get autoUpdate # expect: on
echo "${LATDX_AUTO_UPDATE:-unset}" # expect: unset (any of 0/false/off/no opts out)
echo "${CI:-unset}" # any truthy CI value skips the silent pathWhen opted out, the Update available: ... stderr banner prints instead. Re-enable with latdx config set autoUpdate on or unset the env var.
Force an upgrade manually
latdx upgradelatdx upgrade always runs in the foreground regardless of the silent-update setting, and reports failures interactively.
latdx: command not found
latdx: command not found
The CLI ships as a platform-specific release binary; the shell needs to find it on PATH.
Install the CLI binary
Follow the steps in docs/user/cli-quickstart.md under Install the CLI Binary.
Open a fresh terminal session
So PATH updates from the install step are reloaded.
Verify
latdx --helpBypassing the automatic FLS/OLS grant
You manage latdx_TestRunnerAccess (or an equivalent permset) yourself and want LATdx to stop deploying it, or the running user lacks permission to deploy metadata on a tightly controlled sandbox and you see a warning like Test-runner access grant failed, continuing anyway: ....
The grant is best-effort: LATdx deploys and assigns a permset before each org-mode run. The opt-out env var is read at daemon startup, so the daemon must be restarted for the new value to take effect.
Stop the daemon
So the new env var is picked up on restart:
latdx daemon stopLaunch with the opt-out env var
LATDX_SKIP_TEST_RUNNER_ACCESS=1 latdx test run -o my-org -n MyTestMake it persistent
If you need this consistently, export the variable in your shell profile so every daemon spawn inherits it.
The grant is cached (in memory for the session and on disk at ~/.latdx/runner-access/<orgId>.json), so once warm it adds well under a second per run.
If the org’s schema changes (custom object added/edited), LATdx detects the fingerprint change and regenerates the permset automatically on the next run. Deleting the org’s file under ~/.latdx/runner-access/ forces a full regenerate on the next run.