> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Path Fixing

Coverage reports often contain file paths that don't match your repository structure. This can happen when tests run in different environments (Docker containers, CI runners, different operating systems), when using monorepos or when coverage tools generate absolute paths. Qlty provides path fixing options to resolve these mismatches.

## Common Path Issues

### Absolute Paths

Coverage tools often generate absolute paths that include the full filesystem path or more than the root relative path:

```
/Users/developer/projects/myapp/src/components/Button.js
/home/runner/work/myapp/myapp/src/components/Button.js
/app/src/components/Button.js
```

These should be relative to your repository root:

```
src/components/Button.js
```

### Container Paths

When running tests in Docker containers, paths often include the container's working directory:

```
/app/src/components/Button.js
/workspace/src/components/Button.js
```

### Missing Path Prefixes

Sometimes coverage reports have paths that are missing required prefixes, particularly in case of monorepos or nested projects:

```
components/Button.js  # Missing "/app/javascript/" prefix
app/models/foo.rb     # Missing "server/" prefix
```

#### Jacoco

Some Jacoco projects generate coverage with missing path prefixes where a single path prefix will not suffice. See [Using JACOCO\_SOURCE\_PATH](#using-jacoco_source_path).

## Path Fixing Options

### Strip Prefix

Remove unwanted prefixes from file paths using `--strip-prefix`:

<CodeGroup>
  ```yaml GitHub Actions lines theme={"system"}
  - name: Upload coverage to Qlty
    uses: qltysh/qlty-action/coverage@v2
    with:
        oidc: true
        files: coverage/lcov.info
        strip-prefix: /app/
  ```

  ```bash CLI lines theme={"system"}
  # Remove Docker container path prefix
  qlty coverage publish --strip-prefix=app coverage.lcov

  # Remove absolute path prefix
  qlty coverage publish --strip-prefix=home/runner/work/myapp coverage.lcov
  ```
</CodeGroup>

### Add Prefix

Add required prefixes to file paths using `--add-prefix`:

<CodeGroup>
  ```yaml GitHub Actions lines theme={"system"}
  - name: Upload coverage to Qlty
    uses: qltysh/qlty-action/coverage@v2
    with:
        oidc: true
        files: coverage/lcov.info
        add-prefix: src
  ```

  ```yaml CircleCI lines theme={"system"}
  # Qlty Coverage Orb
  - qlty-orb/coverage_publish:
        files: coverage/coverage.json
        add_prefix: src
  ```

  ```bash CLI lines theme={"system"}
  # Add missing "src/" prefix
  qlty coverage publish --add-prefix=src coverage.lcov

  # Add deeper path prefix
  qlty coverage publish --add-prefix=packages/frontend/src coverage.lcov
  ```
</CodeGroup>

### Combining Options

You can use both `--strip-prefix` and `--add-prefix` together:

```bash lines theme={"system"}
# Remove container path and add correct prefix
qlty coverage publish \
  --strip-prefix=home/runner/work/myapp \
  --add-prefix=src \
  coverage.lcov
```

### Using `JACOCO_SOURCE_PATH`

Java projects with multiple modules often generate coverage for each module with source code paths relative to their module, leaving out its parent directories.

For example, a multi-module Maven project might have source code located in:

```
openpdf-core/src/main/java/
openpdf-fonts-extra/src/main/java/
openpdf-html/src/main/java/
```

But the resulting `jacoco.xml` may not includes these directories when listing source code paths.

To ensure paths are prefixed properly in the final report, specify an environment variable `JACOCO_SOURCE_PATH` with a whitespace-separated list of directories containing Java source code (relative to the repository root). Qlty will resolve source code paths and include the full proper path in its coverage report.

```yaml GitHub Actions with JACOCO_SOURCE_PATH lines theme={"system"}
- name: Upload coverage to Qlty
  uses: qltysh/qlty-action/coverage@v2
  env:
      JACOCO_SOURCE_PATH: openpdf-core/src/main/java openpdf-fonts-extra/src/main/java openpdf-html/src/main/java openpdf-kotlin/src/main/java openpdf-renderer/src/main/java pdf-swing/src/main/java pdf-toolbox/src/main/java
  with:
      oidc: true
      files: "**/target/site/jacoco/jacoco.xml"
```

## Common Scenarios

### Docker Containers

Most Docker setups require stripping the container's working directory:

```bash lines theme={"system"}
# Container uses /app as working directory
qlty coverage publish --strip-prefix=app coverage.lcov

# Container uses /workspace
qlty coverage publish --strip-prefix=workspace coverage.lcov
```

### Monorepos

In monorepos, you may need to add package-specific prefixes:

```bash lines theme={"system"}
# Coverage from a specific package
qlty coverage publish --add-prefix=packages/api coverage.lcov

# Or strip and add for nested structures
qlty coverage publish \
  --strip-prefix=app \
  --add-prefix=services/user-service \
  coverage.lcov
```

### CI Runners

Different CI providers may generate different path structures:

```bash lines theme={"system"}
# GitHub Actions
qlty coverage publish --strip-prefix=home/runner/work/repo-name coverage.lcov

# GitLab CI
qlty coverage publish --strip-prefix=builds/group-name/repo-name coverage.lcov

# CircleCI
qlty coverage publish --strip-prefix=home/circleci/project coverage.lcov
```

## Verifying Path Fixes

### Test with --dry-run

Use dry run to see how paths are being processed:

```bash lines theme={"system"}
qlty coverage publish --strip-prefix=app --dry-run coverage.lcov
```

### Validate After Upload

After uploading, check the coverage report in Qlty's web interface to ensure file paths match your repository structure.

## Language-Specific Examples

### JavaScript/Node.js

```bash lines theme={"system"}
# Jest with Docker
qlty coverage publish --strip-prefix=app coverage/lcov.info
```

### Python

```bash lines theme={"system"}
# Docker with Python
qlty coverage publish --strip-prefix=app coverage.xml

# Virtual environments
qlty coverage publish --strip-prefix=opt/venv/lib/python3.9/site-packages/myapp coverage.xml
```

### Java

```bash lines theme={"system"}
# Maven with Docker
qlty coverage publish --strip-prefix=app target/site/jacoco/jacoco.xml

# Gradle projects
qlty coverage publish --add-prefix=src/main/java build/reports/jacoco/test/jacocoTestReport.xml
```

#### Multi-Module Projects with Jacoco

Jacoco projects may need to specify the environment variable `JACOCO_SOURCE_PATH` when publishing coverage. See [Using JACOCO\_SOURCE\_PATH](#using-jacoco_source_path).

### Go

```bash lines theme={"system"}
# Go modules
qlty coverage publish --strip-prefix=go/src/github.com/user/repo coverage.out
```

### Ruby

```bash lines theme={"system"}
# Rails in Docker
qlty coverage publish --strip-prefix=app coverage/coverage.json

# Bundler paths
qlty coverage publish --strip-prefix=usr/local/bundle/gems coverage.json
```

## Advanced Path Transformations

### Multiple Strip Operations

For complex path structures, you may need multiple transformations:

```bash lines theme={"system"}
# First strip the container path, then add the correct prefix
qlty coverage publish \
  --strip-prefix=app/tmp/build \
  --add-prefix=src/main/java \
  coverage.xml
```

## Troubleshooting

### No Files Matched

If Qlty reports no files were matched:

1. Check that your repository contains the files referenced in the coverage report
2. Verify the path transformations result in valid repository paths
3. Use debug mode to see the transformed paths

### Missing Coverage Data

If some files are missing from the coverage report:

1. Confirm all source files are included in the original coverage report
2. Check that path transformations don't accidentally exclude files
3. Verify the coverage tool configuration includes all relevant files

## See Also

* [Running Tests in Docker](/coverage/running-tests-in-docker) - Docker-specific path fixing examples
* [CI Integration](/coverage/ci) - CI provider-specific path issues
* [Coverage Formats](/coverage/formats) - How different formats handle file paths
* [Troubleshooting](/coverage/troubleshooting) - General coverage upload issues