> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md).
# Troubleshooting
Diagnose setup, access, tagging, reporting, and performance issues in one place.
Start with the symptom, rerun with `--log-level DEBUG`, and then narrow the scope.
{% hint style="info" %}
Use [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md) for short answers. Use [CLI Reference](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md) for exact command syntax.
{% endhint %}
### Setup and configuration
Check Python, installed dependencies, JSON validity, and required settings before you debug anything deeper.
Python module not found
`requests` is not installed in the Python environment that runs the script.
Install the package in that environment, then rerun the same command.
Wrong Python version
The script is running with Python 2.x or an unsupported Python 3 version.
Confirm that `python3 --version` returns Python 3.7 or later, then rerun the script with `python3`.
Permission denied
Your user cannot write to the output folder or install local packages.
Grant write access to the output path or switch to a writable location before rerunning.
Settings file not found
The settings file is missing or the command runs from the wrong directory.
Confirm the file exists and pass the full path if needed.
Invalid JSON in settings
The settings file contains malformed JSON.
Validate the file first, then fix common issues like trailing commas, missing quotes, and unclosed braces.
Invalid JSON in environment variables
A JSON-based environment variable is malformed.
Wrap the whole value in single quotes and keep JSON keys and strings in double quotes.
{% hint style="warning" %}
Empty or malformed environment variables can override valid file values.
{% endhint %}
Missing required settings
One or more required fields are missing.
Confirm the `sealights` block includes `api_token` and `domain`, then add either a `jira` or `ado` block for issue-based reporting.
If you use overrides, confirm they are not replacing valid values with empty ones.
### Authentication and access
Check the token, the base URL, and the account scope in the target system.
SeaLights API token invalid
The SeaLights API token is invalid or expired.
Generate a new token in SeaLights, update the stored value, and test again.
Jira authentication failed
The authorization value is invalid, or the account cannot read the target data.
For Jira Cloud, recreate the Atlassian API token and rebuild the encoded authorization value.
For Jira Server or Data Center, rebuild the credential value that matches your authentication model.
GitHub token invalid
The personal access token is invalid, expired, or missing the required repository scope.
Generate a new token, confirm the correct scope, and update the stored value.
Generate a new token at with the `repo` scope (or `public_repo` for public repositories only).
Azure DevOps PAT expired
The PAT is expired, invalid, or missing the required permissions.
Create a new PAT with **Work Items: Read** and **Extension Data: Read & Write** if you use the Azure DevOps plugin.
{% hint style="warning" %}
A valid token can still fail if the account does not have project or repository access.
{% endhint %}
### Source Tagging
Check the repository name, ticket pattern, app mapping, and time window.
No PRs found
No pull requests were found in the selected time range, or the repository name does not match the SCM record.
Increase `--days-back`, then confirm the repository name matches the source system exactly.
Use [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging) for the exact command options.
Ticket ID not extracted
The regex pattern does not match the real PR title or commit message format.
Test the pattern against real text, then update `key_pattern_regex` to match your ticket format.
Common patterns include Jira keys like `[A-Z]+-[0-9]+`, GitHub issues like `#[0-9]+`, and numeric Azure DevOps work item IDs.
```bash
python3 -c "
import re
text = '[PROJ-123] Add feature'
pattern = 'PROJ-[0-9]+'
match = re.search(pattern, text)
print(match.group() if match else 'No match')
"
```
Git clone or pull failed
This affects only the history-based tagging flow.
SSH keys may not be loaded, public keys may not be registered, or HTTPS credentials may not be configured for non-interactive access.
Use [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging) for the history-based flow and [Security Considerations](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/security-considerations.md) for secure credential handling.
App or branch not found in SeaLights
The configured app or branch name does not exist in SeaLights.
Confirm that `coverage_app_list` and `repo_list` use the exact application and branch names that SeaLights reports.
{% hint style="warning" %}
App names, branch names, and repository names are often case-sensitive.
{% endhint %}
### Report and Coverage
Check the ticket query, SeaLights build data, lookback window, and generated report files.
#### No tickets found
Validate the ticket query in the source system before you rerun the report. Choose the ticket source that matches the failing query.
{% tabs %}
{% tab title="Jira" %}
**✅ Prerequisites**
* The account can read the target projects.
* The JQL works in the Jira UI.
**🚀 Steps**
{% stepper %}
{% step %}
#### Test the query in Jira
Go to Issues → Search → Advanced and run the same JQL.
{% endstep %}
{% step %}
#### Broaden the scope
Expand the time range and confirm the project key is correct.
{% endstep %}
{% step %}
#### Retest through the API
Confirm the same query returns issues through the API before rerunning the script.
{% endstep %}
{% endstepper %}
**📤 Expected outcome**
The query returns issues in both the UI and the API.
{% endtab %}
{% tab title="Azure DevOps" %}
**✅ Prerequisites**
* The account can read the target project.
* The WIQL returns work items in the Azure DevOps UI.
**🚀 Steps**
{% stepper %}
{% step %}
#### Open queries
Go to Boards → Queries.
{% endstep %}
{% step %}
#### Run the WIQL
Run the same WIQL in the browser.
{% endstep %}
{% step %}
#### Broaden the scope
Expand the date range and confirm the project and team scope are correct.
{% endstep %}
{% endstepper %}
**📤 Expected outcome**
The query returns work items before you rerun the script.
{% endtab %}
{% endtabs %}
Failed to create coverage report
SeaLights did not find matching builds in the selected range.
Increase `coverage_days_back`, then confirm the app and branch names match SeaLights exactly.
Report timeout
The report scope is too large or the timeout is too short.
Increase `report_timeout_minutes`, reduce the number of tickets, or narrow the app and branch scope.
No coverage data in reports
The source code was not tagged, or the tagged builds fall outside the reporting window.
{% stepper %}
{% step %}
### Confirm tagging ran
Make sure the tagging flow completed for the target repositories.
{% endstep %}
{% step %}
### Check the ticket IDs
Confirm the tagged ticket IDs match the reporting query exactly.
{% endstep %}
{% step %}
### Widen the coverage window
Increase `coverage_days_back` if the tagged builds are older than the current lookback period.
{% endstep %}
{% endstepper %}
Missing ReportInfo files
The report creation step did not run, failed early, or wrote to a different output folder.
Confirm the report-generation step completed and that the configured output folder contains `ReportInfo_*.json`.
Use [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation) for the exact output flow.
{% hint style="warning" %}
Do not debug empty coverage until you confirm that ticket queries, SeaLights builds, and `ReportInfo_*.json` files all exist.
{% endhint %}
### Network and performance
Separate connectivity problems from scope and runtime problems.
SSL certificate verification failed
Self-signed certificates, corporate proxies, or missing CA bundles can break TLS verification.
Use platform-specific `verify_ssl` overrides only for temporary diagnosis.
Install the correct CA chain or point Python to a trusted CA bundle for the long-term fix.
{% hint style="warning" %}
Do not keep `verify_ssl: false` as a permanent fix.
{% endhint %}
```bash
# Linux
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
# macOS
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain corporate-ca.crt
# Or point Python directly to a CA bundle
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
```
Rate limiting
The integration is sending too many API requests.
Wait for the limit window to reset, reduce the request volume, and increase the time between runs.
Typical limits: GitHub's default API limit resets hourly (check with `curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit`); Azure DevOps allows roughly 200 requests per user per hour.
Connection timeout
The network is unstable, blocked, or too slow for the current scope.
Confirm outbound access, validate proxy settings, and retry with a smaller scope if needed.
Slow tagging
The run covers too many days or too many repositories.
Reduce `--days-back`, split repositories across separate jobs, or switch to a narrower tagging path.
Memory issues
The query scope is too large for the available memory.
Split the work into smaller batches, reduce `child_levels`, and process repositories individually.
Slow report generation
The report scope is too large.
Reduce `coverage_days_back`, narrow the ticket set, process tickets in batches, or reuse an existing report ID.
### Security Troubleshooting
Treat trust, identity, and authorization issues separately.
SSL certificate errors
Install the missing CA certificate in the system trust store or point Python to a trusted CA bundle with `REQUESTS_CA_BUNDLE`.
If your network intercepts HTTPS traffic, install the proxy CA certificate too.
Authentication failures
Expired tokens, incorrect auth encoding, missing token scopes, and missing project permissions are the most common causes.
Check token scope first, then confirm the base URL, header format, and target access.
Git authentication issues
SSH keys may not be loaded into `ssh-agent`, public keys may not be registered, or HTTPS credentials may not be available for non-interactive access.
Use [Installation and first run](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/installation.md) for the initial setup path.
If credentials are compromised
{% stepper %}
{% step %}
### Revoke the exposed token
Remove the token in the source system immediately.
{% endstep %}
{% step %}
### Replace it everywhere
Generate a replacement token and update every environment that uses it.
{% endstep %}
{% step %}
### Review the exposure
Check audit logs and fix the process that allowed the leak.
{% endstep %}
{% endstepper %}
Prevent repeat issues
Use CI secret managers or environment variables, mask secrets in logs, apply least-privilege access, rotate tokens on a schedule, and keep local settings files out of source control.
### Troubleshooting Questions
Use these quick checks when you already know the symptom.
Where can I find error logs?
Rerun the failing command with `--log-level DEBUG` and save the output to a file for review.
The tool says "No tickets found" but I can see them in Jira or Azure DevOps
Confirm the JQL or WIQL returns results in the web UI, then confirm the same credentials and base URL work through the API.
Reports show `0%` coverage for all tickets
This usually means the code changes were not tagged or the coverage window excludes the relevant test runs.
Follow the **No coverage data in reports** flow above.
How do I debug regex pattern matching?
Test the pattern against a real PR title or commit message and compare the match against your expected ticket format.
Use [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging) for the tagging flows and setting names.
How do I confirm environment variables are overriding my settings file?
List the active override variables, compare them with the settings file, and remove any empty or malformed values.
Use [Environment variables](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#environment-variables) for the supported overrides.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.