CLI Troubleshooting

1) Daemon connection issues

Symptoms:

• Runs hang on daemon connect.
• Errors mentioning socket/connect/request timeout.

Actions:

1. Retry in verbose mode to capture details:

   latdx test run -n MyTest -o my-org -v

2. Check daemon/cache state:

   latdx cache status

3. Clear daemon/cache artifacts and retry:

   latdx cache clear --all

4. Rerun the original command. Org mode can still fall back to direct core execution when daemon fails.

2) Org/package readiness issues

Symptoms:

• Package not installed/outdated errors.
• Org alias resolution issues.

Actions:

1. Verify auth/default org:

   sf org list

2. Pass explicit org alias:

   latdx test run -n MyTest -o my-org

   For list mode:

   latdx test list -o my-org

3. Check package status quickly:

   latdx --version -o my-org

4. If using source install mode, verify source path inputs (LATDX_SF_SOURCE_PATH) and repo checkout.

3) Debug log storage exceeded

Symptoms:

• Error indicates debug log storage exceeded.
• Run stops before normal test results complete.

Actions:

1. Accept CLI prompt to delete logs and retry when offered.
2. If needed, rerun command and confirm cleanup prompt.
3. Reduce repeated high-volume runs while diagnosing and use targeted test selection.

4) Compilation/test failures

Symptoms:

• Compile problems in output.
• Tests fail with stack traces or class/method errors.

Actions:

1. Re-run with verbose output:

   latdx test run -n MyTest -o my-org -v

2. Isolate execution strategy:
   • Add --sequential
   • Add --fullSim
3. Narrow scope to one test method:

   latdx test run -t MyTest.testMethod -o my-org

4. If file mode, verify selected path exists and contains Apex test methods:

   latdx test list -f force-app/main/default/classes/MyTest.cls

5) Input validation errors

Symptoms:

• Messages like:
  • Cannot use --class-names or --tests with --file or --dir
  • Cannot use --method with --dir or org mode

Actions:

1. Choose exactly one input family per run:
   • Org mode: --class-names or --tests (or no file/dir)
   • File mode: --file or --dir
2. Use --method only with --file.

6) latdx: command not found

Symptoms:

• Shell returns latdx: command not found.

Actions:

1. Install the CLI binary as described in docs/user/cli-quickstart.md under Install the CLI Binary.
2. Open a new terminal session so PATH updates are reloaded.
3. Verify:

   latdx --help

7) Bypassing the automatic FLS/OLS grant

Symptoms:

• You manage latdx_TestRunnerAccess (or an equivalent permset) yourself and want LATdx to stop deploying it.
• 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: ....

Actions:

1. Stop the daemon so the new env var is picked up on restart:

   latdx daemon stop

2. Launch latdx test run with the opt-out env var:

   LATDX_SKIP_TEST_RUNNER_ACCESS=1 latdx test run -o my-org -n MyTest

3. If you need this consistently, export the var in your shell profile so every daemon spawn inherits it.

Notes:

• 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.