---
title: Test Parallelization Troubleshooting
description: >-
  Diagnose missing plans, unexpected test selection, tracer errors, and parallel
  worker failures.
breadcrumbs: >-
  Docs > Test Optimization in Datadog > Test Parallelization > Test
  Parallelization Troubleshooting
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Test Parallelization Troubleshooting

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

`ddtest` reports fatal errors as `[error_code] message`; read the message and framework output in your CI logs for the specific cause.

## Missing or invalid plan artifacts{% #missing-or-invalid-plan-artifacts %}

For errors such as `run_plan_load_failed` or `run_ci_node_test_files_missing`:

1. Generate a fresh plan in the planning job.
1. Transfer the **complete** `.testoptimization/` directory to every test job, including hidden files and caches.
1. Run from the same project directory as planning. Confirm `manifest.txt` is directly inside `.testoptimization/`, not another nested directory.
1. Pass a zero-based `--ci-node` matching an assignment in `runner/tests-split/`.

On GitHub Actions, use `include-hidden-files: true` when uploading. Artifact paths are relative to the workspace, even if shell steps set a different working directory.

On CircleCI, use the same pipeline-specific key for saving and restoring the cache, without prefix fallback keys. A revision-only key can restore a different run's plan. Do not generate a replacement plan independently in each worker.

## Planning is slow for Ruby or Python{% #planning-is-slow-for-ruby-or-python %}

If test discovery makes planning slow, consider suite-level skipping. Set `DD_TESTOPTIMIZATION_TIA_TEST_SKIPPING_MODE` to `suite` in the CI environment for both planning and test jobs.

This reduces discovery work by finding test files instead of individual tests. For pytest, it avoids collection and imports of test modules and `conftest.py`. The tradeoff is less precise skipping: Test Impact Analysis skips or runs entire suites, so more tests may run.

See [suite-level skipping for Ruby and Python](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#use-suite-level-skipping-for-ruby) and [pytest suite mode](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#pytest-suite-mode) for details.

## Unexpected CI node or worker count{% #unexpected-ci-node-or-worker-count %}

Check these settings in the **planning job**:

- `--min-parallelism` and `--max-parallelism` bound the count. Both default to the available physical CPU count.
- `--ci-job-overhead` favors fewer runners as it increases. The default is `25s`; `0s` removes the penalty without forcing maximum parallelism.
- `--target-time` sets a duration target. If no split meets it, the planner selects the fastest expected split within the bounds.

In CI-node mode, the plan count means CI nodes, and `--ci-node-workers` controls processes per node. On one node without `--ci-node`, the plan count means local processes. A plan selecting one node is valid. See [parallelism tuning](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#choose-a-parallelism-budget).

## No skippable tests are applied{% #no-skippable-tests-are-applied %}

WebdriverIO supports balancing but does not support Test Impact Analysis skipping.

Check that:

- Test Impact Analysis is enabled for the test service.
- Git is installed and `ddtest` runs inside the intended Git checkout.
- Planning and execution use the same `DD_SERVICE`, suite, source revision, OS, and language runtime.
- Runtime tags match the environment used to calculate skippable tests.

Ruby and Python can fall back to file discovery when full discovery fails or a Datadog SDK is absent. Check the discovery logs before assuming a successful plan applied test-level skipping. `--strict-discovery` makes full-discovery failures fatal; canceled full discovery still falls back.

See [runtime tags](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#stabilize-runtime-tags) and [Test Impact Analysis troubleshooting](https://docs.datadoghq.com/tests/test_impact_analysis/troubleshooting.md).

## Pytest reports an import file mismatch or missing tests{% #pytest-reports-an-import-file-mismatch-or-missing-tests %}

Python test files with the same basename can conflict under pytest's default import mode. `ddtest` separates them when the selected runner count is sufficient. When distributing files, it retains all otherwise runnable files and warns if duplicate basenames must share a runner, including with a single runner.

To resolve conflicts, do one of the following:

- Add `__init__.py` files so the tests have distinct fully qualified module names.
- Rename the conflicting files.
- Configure pytest with `--import-mode=importlib`.

Basename warnings can still appear after you fix imports. Splitting does not prevent collisions during full discovery, which collects tests before distribution. If a warning lists files missing from full-discovery results, investigate them: those files are not scheduled.

In [pytest suite mode](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#pytest-suite-mode), normal file-only planning does not apply selectors such as `-k` and `-m`; pytest applies them during execution. Forced full discovery also applies them during planning. `ddtest` treats a suite-mode worker's pytest exit code 5 as success, so an entirely deselected run can succeed. Check the selectors and planned files when no tests execute. Test mode preserves exit-code-5 failures from pytest workers, but an empty plan can still succeed without starting pytest.

## Planning works but execution cannot load the tracer{% #planning-works-but-execution-cannot-load-the-tracer %}

Planning does not require a Datadog SDK; execution does. Keep [Test Optimization setup](https://docs.datadoghq.com/tests/setup.md) in every test job.

For Python, check the environment used by the configured launcher. For JavaScript, check the existing Datadog CI require in `NODE_OPTIONS`, then `DD_TRACE_PACKAGE`, then the project-local `dd-trace` package. An invalid explicit preload causes an error instead of falling back to another installation.

Keep project loaders and action-provided tracer paths. Do not overwrite `NODE_OPTIONS` or add a second tracer to work around a resolution error. See [JavaScript instrumentation](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#javascript-test-discovery-and-instrumentation).

## Minitest does not run the selected files{% #minitest-does-not-run-the-selected-files %}

In a detected Rails application, `ddtest` passes files as positional arguments. Use its Rails default or a compatible `bin/rails test` or `bundle exec rails test` override. A `rake test` override does not change the file-forwarding mode. Preserve custom Rake setup before switching commands.

For non-Rails projects, `ddtest` passes assigned files through `TEST_FILES`. Update the existing `Rake::TestTask` after its normal configuration:

```ruby
Rake::TestTask.new(:test) do |test|
  # Keep the task's existing file list and other settings above this line.
  test.test_files = ENV["TEST_FILES"].split if ENV["TEST_FILES"]
end
```

## Custom commands do not run the expected files{% #custom-commands-do-not-run-the-expected-files %}

Compare the original command, configuration, and environment with both the planning and execution steps. Preserve filters, seeds, reporters, shared setup, and suite boundaries.

`--command` must invoke the selected framework through a supported launcher. Shell chains and scripts that run multiple frameworks are not supported. Vitest rejects command overrides entirely.

Framework-specific checks:

| Framework   | What to check                                                                                                                                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pytest      | `--tests-location` must match files. Preserve `PYTEST_ADDOPTS` and the environment used by the launcher. For multiple roots, use one brace glob such as `'{tests/unit,tests/integration}/**/test_*.py'`.                                                                                             |
| Jest        | Keep configuration and selection flags, including an existing `--runInBand`.                                                                                                                                                                                                                         |
| Mocha       | Keep all suite paths and shared `--file` or `--require` setup. `ddtest` replaces configured `spec` inputs during execution.                                                                                                                                                                          |
| Cucumber.js | Paths and rerun files select features during discovery, but execution runs assigned feature files. Use tag or name filters to preserve scenario scope.                                                                                                                                               |
| Cypress     | `ddtest` owns `--spec`. Put a subset in `--tests-location` or Cypress configuration.                                                                                                                                                                                                                 |
| Playwright  | Keep the package directory, configuration, and selected projects. Remove native `--shard` when using `ddtest` splits.                                                                                                                                                                                |
| Vitest      | Remove `--command` and `DD_TEST_OPTIMIZATION_RUNNER_COMMAND`. Use the same `--vitest-config` in both phases and move command options into that configuration.                                                                                                                                        |
| WebdriverIO | Keep the configuration and capability selections. Grouped specs cannot be distributed as independent files, and remote cloud grids are not supported. See [WebdriverIO setup](https://docs.datadoghq.com/tests/test_parallelization/setup.md?prog_lang=javascript&platform=webdriverio#webdriverio). |

A package-manager separator before the framework executable is preserved. A framework's own `--` ends its options; `ddtest` inserts discovery flags before it and replaces the file selection after it during execution. See [Custom test commands](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#custom-test-commands).

## Tests pass but coverage or reports are missing{% #tests-pass-but-coverage-or-reports-are-missing %}

Check the expected suite and project selection, not only the exit status. Preserve the original reporters, output paths, coverage provider and thresholds, and upload steps. Give concurrent workers distinct output paths or artifact names.

Vitest's Node.js API does not run package-script preparation or npm life cycle commands. Move those steps before `ddtest` and retain reporting and coverage options in the selected config. See [Configure Vitest](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#vitest).

## Tests fail only in parallel{% #tests-fail-only-in-parallel %}

Look for shared databases, ports, temporary files, browser displays, and report paths. Keep application startup and readiness checks in each execution job. Use [worker isolation](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#isolate-workers) and lower parallelism while investigating.

Do not combine `ddtest` assignments with another whole-suite splitter. Check that each worker runs its assignment and that the original full-suite command no longer runs alongside it.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Set up Test Parallelization](https://docs.datadoghq.com/tests/test_parallelization/setup.md)
- [Test Parallelization settings reference](https://docs.datadoghq.com/tests/test_parallelization/configuration.md)
- [Troubleshoot Test Optimization](https://docs.datadoghq.com/tests/troubleshooting.md)
