---
title: "Troubleshoot test splitting"
description: "Tips and common errors to help troubleshoot your CircleCI test splitting implementation."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-15"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Troubleshoot test splitting

## Using test splitting with Python Django tests

To use test splitting with CircleCI, you must pass in a list of tests to run. However, due to how Django executes tests, you cannot glob the tests and pass them in directly.

Sometimes, users run into specific issues when performing test splitting for their own unique use cases. One example of a user resolving an issue when test splitting in Python Django did not perform correctly can be found in the following [Discuss post](https://discuss.circleci.com/t/python-django-tests-not-being-split-correctly/36624).

Using this example, here is a quick example of how you can accomplish test splitting:

```yaml
- run:
    command: |
      # get test files while ignoring __init__ files
      TESTFILES=$(circleci tests glob "catalog/tests/*.py" | sed 's/\S\+__init__.py//g')
      echo $TESTFILES | tr ' ' '\n' | sort | uniq > circleci_test_files.txt
      cat circleci_test_files.txt
      TESTFILES=$(circleci tests split --split-by=timings circleci_test_files.txt)
      # massage filepaths into format manage.py test accepts
      TESTFILES=$(echo $TESTFILES | tr "/" "." | sed 's/\.py$//g')
      echo $TESTFILES
      pipenv run python manage.py test --verbosity=2 $TESTFILES
```

## Using test splitting with `pytest`

If you try to split your tests across containers with `pytest`, you may encounter any of the following errors:

```shell
No timing found for "tests/commands/__init__.py"
No timing found for "tests/commands/test_1.py"
No timing found for "tests/commands/test_2.py"
```

If any of these errors are returned, you may need to make a few adjustments, which are listed below.

### Are you setting a custom `working_directory`?

If so, you may need to adjust the file paths that are saving to your test metadata XML file. Alternatively, try working out of the standard working directory to see if that resolves the issue. Remove any `working_directory` instances from your test run job.

### Where does your `pytest.ini` live?

To ensure test splitting performs correctly, make sure you are running your tests in the root directory. If your tests are not being run in the root directory, you may need to run the following command before you test the `run` command:

```shell
cp -f .circleci/resources/pytest_build_config.ini pytest.ini
```

The `.circleci/resources/pytest_build_config.ini` path may need to be replaced to point to where it is located in your project.

### Are you setting the `junit_family` in your `pytest.ini`?

Check to see if you have something like `junit_family=legacy` set in your `pytest.ini` file. For more information on how to set `junit_family`, refer to the `pytest` [docs](https://docs.pytest.org/en/stable/_modules/_pytest/junitxml.html). Search for "families" to see the relevant information.

A breaking change was introduced in `pytest` 6.1, the `junit_family` XML format changed to `xunit2`, which does not include filenames. This means that `--split-by=timings` will not work unless you specify `xunit1`. For more information see the [pytest changelog](https://docs.pytest.org/en/stable/changelog.html#id137). If this is your issue, you may see the following error:

```shell
Error autodetecting timing type, falling back to weighting by name. Autodetect no matching filename or classname.  If file names are used, double check paths for absolute vs relative.
```

### Example project that correctly splits by timings

The example below is from the [`sample-python-cfd` project](https://github.com/CircleCI-Public/sample-python-cfd) and shows an implementation of test splitting:

```yml
version: 2.1
orbs:
  python: circleci/python@1.2
jobs:
  build-and-test:
    parallelism: 2
    docker:
      - image: cimg/python:3.8
    steps:
      - checkout
      - python/install-packages:
          pkg-manager: pip
      - run:
          name: Run tests
          command: |
            set -e
            TEST_FILES=$(circleci tests glob "openapi_server/**/test_*.py" | circleci tests split --split-by=timings)
            mkdir -p test-results
            pytest --verbose --junitxml=test-results/junit.xml $TEST_FILES
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: test-results
workflows:
  sample:
    jobs:
      - build-and-test
```

### Video: troubleshooting globbing

To follow along with the commands in the video below you will need to be [`SSH-ed into a job`](https://circleci.com/docs/guides/server/execute/ssh-access-jobs/).

## Other ways to split tests

Some third party applications and libraries might help you to split your test suite. These applications are not developed or supported by CircleCI. Check with the owner if you have issues using it with CircleCI. If you are unable to resolve the issue, you can search and ask on our [Discuss](https://discuss.circleci.com/) forum.

*   **[Knapsack Pro](https://knapsackpro.com)** - Enables allocating tests dynamically across parallel CI nodes, allowing your test suite execution to run faster. See the [CI build time graph examples](https://docs.knapsackpro.com/2018/improve-circleci-parallelisation-for-rspec-minitest-cypress) for details.
    
*   **[`phpunit-finder`](https://github.com/previousnext/phpunit-finder)** - A helper CLI tool that queries `phpunit.xml` files to get a list of test filenames and print them, useful for splitting tests in parallel based on CI timings.
    
*   **[`go list`](https://golang.org/cmd/go/#hdr-List_packages_or_modules)** - Use the built-in Go command `go list ./…​` to glob Golang packages. This allows splitting package tests across multiple containers.
    

```shell
go test -v $(go list ./... | circleci tests split)
```

## Next steps

*   [Upload Test Results](https://circleci.com/docs/guides/server/test/collect-test-data/)