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 and the managed package is installed.
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 and package readiness issues
Package not installed/outdated errors, or org alias resolution issues.
LATdx requires an authenticated org and the latdx-sf managed package (or a source install) 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-orgCheck package status quickly
latdx --version -o my-orgVerify source install inputs
If using source install mode, confirm LATDX_SF_SOURCE_PATH and the repo checkout point at a valid sfdx-project.json workspace.
Set 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 (CI=true 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 typically 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.
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 two ways: in-memory on the LatdxCore instance, and on disk at ~/.latdx/runner-access/<orgId>.json. With the cache warm, the grant step 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.