Troubleshooting

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.

​

Upload Issues

​

Coverage Report Not Being Detected

• “Unsupported format” errors
• “Unable to parse coverage report” messages
• No coverage data appears in Qlty after upload

• Unsupported coverage format
• Corrupt or incomplete coverage report
• Incorrect file path in upload command

1. Verify your coverage format is supported
2. Check that the coverage report file exists and is complete
3. Try using the --format flag to explicitly specify the format:
   qlty coverage publish --format=lcov path/to/coverage.info
   
4. Examine the report file for valid content
5. Generate a fresh coverage report and try again

​

Authentication Failures

• “Authentication failed” errors
• “Invalid token” messages
• “Permission denied” errors

• Incorrect coverage token
• Expired or rotated token
• Missing environment variable
• Using a token with incorrect scope

1. Verify your token is correct in your CI settings
2. Check environment variable names (should be QLTY_COVERAGE_TOKEN)
3. Regenerate your token in Qlty and update your CI configuration
4. Ensure you’re using the token for the correct workspace or project
5. If using OIDC, verify the permissions configuration in your GitHub workflow

​

OIDC Token Failures on Forked PRs

• Error: Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable
• Coverage upload failures specifically on forked pull requests
• OIDC authentication is working for regular PRs but failing on forks

• GitHub Actions security restrictions prevent OIDC token generation in workflows triggered by forked pull requests

​

Path Mapping Issues

• Coverage appears but doesn’t match files in your repository
• “File not found” errors when viewing coverage
• Coverage shown for files that don’t exist in your repo

• Coverage report contains absolute paths
• Path structure differs between build environment and repository
• Generated files with different paths

1. See Path Fixing for detailed solutions.

​

S3 Upload Failures (403 Errors)

• HTTP 403 Forbidden errors during coverage upload
• “Access denied” messages when uploading to S3
• Coverage upload fails with permission errors

• Restrictive AWS VPC endpoint policies that block cross-account S3 operations
• VPC endpoint policy doesn’t allow s3:PutObject action to other AWS accounts

{
  effect = "Allow"
  actions = ["s3:PutObject"]
  resources = ["*"]
  principals = {
    type = "AWS"
    identifiers = ["*"]
  }
  conditions = [
    {
      test = "StringEquals"
      variable = "aws:PrincipalAccount"
      values = ["QLTY_AWS_ACCOUNT_ID"]
    },
    {
      test = "StringEquals"
      variable = "aws:ResourceAccount"
      values = ["QLTY_AWS_ACCOUNT_ID"]
    }
  ]
}

​

Default Branch Coverage Not Displayed

• Banner shows “We’ve received coverage reports; we haven’t yet received a report for your default branch”
• Coverage uploads exist but the project dashboard doesn’t display default branch coverage

​

Coverage config not yet merged to default branch

​

Default branch also a base branch for a long lived PR

# First publish (handles PR coverage as usual)
qlty coverage publish <your-existing-flags> <coverage-files>

# Second publish (only on default branch, forces branch classification)
if [ "$CIRCLE_BRANCH" = "main" ]; then
  qlty coverage publish --override-pr-number "" <your-existing-flags> <coverage-files>
fi

​

Missing Metadata

• Coverage is uploaded but not associated with the correct branch
• Coverage doesn’t appear in pull requests
• Coverage data shows with incorrect commit information

• CI system metadata not detected
• Shallow git clone in CI
• Custom CI setup not recognized by Qlty

1. Manually specify metadata with override flags:
   qlty coverage publish --override-branch=main --override-commit-sha=abcdef123 coverage.xml
   
2. Ensure your CI environment provides standard environment variables
3. Use a deeper git clone in CI (or fetch git metadata)
4. Check that the git repository is available in the CI environment

​

Viewing Issues

​

Coverage Not Showing in GitHub

• No coverage status checks on pull requests
• Missing coverage comments on pull requests
• Coverage data visible in Qlty but not in GitHub

• GitHub app permissions issues
• Coverage gates not enabled
• PR comments not configured
• Timing issues with CI and status reporting

1. Verify GitHub integration settings in project settings
2. Check that coverage gates are enabled in quality gates settings
3. Ensure PR comments are enabled
4. Check GitHub app permissions in your organization settings
5. Try manually uploading coverage for the PR branch

​

Inconsistent Coverage Reports

• Coverage fluctuates between builds without code changes

• Test flakiness or non-deterministic tests
• Cache issues in tests
• Different coverage tool configurations

​

Missing Coverage for Some Files

• Some files show no coverage data
• Certain directories are missing from coverage reports
• Coverage appears for some languages but not others

• Include/exclude patterns filtering out files
• Multi-language projects with incomplete coverage setup
• Files not being exercised by tests
• Generated code or third-party code inclusion/exclusion

1. Check your coverage tool’s include/exclude configuration. See Excluding Files from Coverage for language-specific examples.
2. Verify that all relevant files are included in coverage report generation. See our documentation on Incomplete or Missing Coverage Reports for more detail.
3. Set up coverage for each language in multi-language projects
4. Use multiple coverage reports for different parts of the codebase

​

Quality Gate Issues

​

Failing Coverage Gates

• Pull requests failing due to coverage checks
• “Coverage decreased” warnings even with improved test coverage
• Diff coverage failing despite high coverage in changed files

• Thresholds set too high for your project’s current state
• Coverage decreasing in files not directly modified
• Base branch coverage calculation issues
• Coverage calculation includes excluded files

1. Adjust coverage gate thresholds to realistic levels
2. Investigate unexpected coverage changes
3. Temporarily disable gates while building up coverage
4. Exclude irrelevant files in your coverage tool so they don’t affect gates
5. Focus on diff coverage rather than total coverage for incremental improvement

​

Coverage Badges Not Updating

• Outdated coverage percentage in badges
• Coverage badge shows “unknown” or “N/A”
• Badge doesn’t reflect recent coverage improvements

• Badge caching
• No coverage data for default branch
• Badge URL issues

1. Ensure coverage is being uploaded for your default branch
2. Check badge URLs and project settings
3. Manually refresh cached badges
4. Verify that the badge is pointing to the correct project and metric
5. Wait for cache expiration (typically a few hours)

​

Merging

​

Coverage Data Missing

• Qlty reports less coverage for a source file than expected. For example, a line is covered according to the raw coverage data, but Qlty shows the line as not covered
• Qlty does not show coverage data for a file

1. Ensure that Qlty has received all partial reports (uploads). The best diagnostic tool is the list of coverage uploads browsable on qlty.sh at Project Settings => Code Coverage. Search for the commit sha, pull request (e.g. refs/pull/5), or branch (e.g. refs/heads/branchName). You should see N “incomplete” reports representing the N uploads Qlty received as well as 1 “complete” report, representing a completion of the report. If you see less than you expect, check that:
   • Every upload attempt succeeded. Did the CLI report “Upload successful” at the end of its output? If not, what error occurred?
   • Every coverage report attempted an upload. Providing a unique name with every coverage report (with --name) can help pinpoint a missing coverage report. (The name will be show in the coverage upload detail page)
   • Each upload is associated with the same expected tag (or no tag)
   • Investigate Incomplete or Missing Coverage Reports

​

Coverage Tag Issues

• Tagged coverage not appearing separately
• Incorrect coverage shown for specific tags
• Tags not filtering correctly in UI

• Incorrect tag specification during upload
• Mixing tagged and untagged uploads
• UI filtering confusion

1. Verify tag naming in upload commands:
   qlty coverage publish --tag=unit coverage.xml
   
2. Ensure consistent tag usage across uploads
3. Check tag configuration in project settings
4. Use different tags for different test types (unit, integration, etc.)

​

Large Repository Issues

• Coverage uploads timing out
• Very slow coverage rendering in UI
• Missing coverage for some files in large repositories

• Coverage reports too large
• Too many files included in coverage
• Performance limits in browser extensions

1. Exclude irrelevant files in your coverage tool to limit coverage to relevant code
2. Split large repositories into smaller projects
3. Exclude generated code, vendor code, or test code from your coverage reports
4. Use more specific coverage focus for very large repositories
5. Contact Qlty support for help with large-scale deployments

​

Getting Additional Help

1. Contact Support: Reach out to Qlty support
2. Join Discord: Ask for help in our Discord community
3. GitHub Issues: Submit a bug report on our GitHub issue tracker

• The exact command you’re running
• Any error messages (with sensitive information redacted)
• Your CI provider and configuration
• The coverage tool and language you’re using
• Steps you’ve already taken to troubleshoot