# Troubleshooting

Common issues and solutions for the User Story Coverage Tagging tool.

## Table of Contents

* [Installation Issues](#installation-issues)
* [Configuration Issues](#configuration-issues)
* [Authentication Issues](#authentication-issues)
* [Tagging Issues](#tagging-issues)
* [Report Generation Issues](#report-generation-issues)
* [API Issues](#api-issues)
* [Performance Issues](#performance-issues)

***

## Installation Issues

### Python Module Not Found

**Error:**

```
ImportError: No module named 'requests'
ModuleNotFoundError: No module named 'requests'
```

**Cause:** The `requests` library is not installed.

**Solution:**

```bash
pip install requests

# Or with specific Python version
python3 -m pip install requests

# Or for user installation
pip install --user requests
```

### Wrong Python Version

**Error:**

```
SyntaxError: invalid syntax
```

**Cause:** Using Python 2.x instead of Python 3.7+

**Solution:**

```bash
# Check Python version
python3 --version

# Ensure it's 3.7 or higher
# Use python3 explicitly
python3 US1_RPT_create_report_info_files.py --settings settings
```

### Permission Denied

**Error:**

```
PermissionError: [Errno 13] Permission denied
```

**Cause:** No write permissions for output directory or pip installation.

**Solution:**

```bash
# For output directory
chmod +w ./reports
# or
mkdir -p ~/reports
# Update settings output_folder

# For pip
pip install --user requests
```

***

## Configuration Issues

### Settings File Not Found

**Error:**

```
FileNotFoundError: [Errno 2] No such file or directory: 'settings'
```

**Cause:** Settings file doesn't exist in current directory.

**Solution:**

```bash
# Create from sample
cp settings.sample settings

# Or specify full path
python3 US1_RPT_create_report_info_files.py --settings /path/to/settings

# Or use environment variables instead
export SEALIGHTS_API_TOKEN="..."
python3 US1_RPT_create_report_info_files.py
```

### Invalid JSON in Settings

**Error:**

```
json.decoder.JSONDecodeError: Expecting ',' delimiter: line 15 column 5
```

**Cause:** Malformed JSON in settings file.

**Solution:**

```bash
# Validate JSON
python3 -m json.tool settings

# Common issues:
# - Trailing commas after last item
# - Missing quotes around strings
# - Unclosed brackets/braces
# - Single quotes instead of double quotes

# Fix example:
{
  "key": "value",  # ❌ Trailing comma on last item
  "key2": value2   # ❌ Missing quotes
}

# Should be:
{
  "key": "value",
  "key2": "value2"
}
```

### Environment Variable JSON Parsing

**Error:**

```
json.decoder.JSONDecodeError: Extra data
```

**Cause:** Invalid JSON in environment variable.

**Solution:**

```bash
# Correct format for arrays
export TEST_STAGES='[{"name":"Unit","reportJsonKey":"unit","reportTitle":"Unit"}]'

# Correct format for objects
export JIRA_CUSTOM_FIELDS='{"summary":"customfield_10917"}'

# Use single quotes around JSON
# Use double quotes inside JSON
```

### Missing Required Settings

**Error:**

```
KeyError: 'api_token'
AttributeError: 'NoneType' object has no attribute 'get'
```

**Cause:** Required configuration missing.

**Solution:**

Ensure all required fields are present:

```json
{
  "sealights": {
    "api_token": "required",
    "domain": "required",
    "coverage_days_back": "required"
  },
  "jira": {
    "authorization": "required",
    "jql": "required",
    "base_url": "required",
    "api_version": "required"
  }
}
```

***

## Authentication Issues

### SeaLights API Token Invalid

**Error:**

```
Failed to get the apps from Sealights: 401 - {"message": "Unauthorized"}
```

**Cause:** Invalid or expired API token.

**Solution:**

1. Generate new token in SeaLights web UI
2. Update settings or environment variable:

```bash
export SEALIGHTS_API_TOKEN="new-token-here"
```

### Jira Authentication Failed

**Error:**

```
Failed to get the Jira tickets: 401 - Unauthorized
Failed to get the Jira tickets: 403 - Forbidden
```

**Cause:** Invalid credentials or insufficient permissions.

**Solution:**

**For Jira Cloud:**

```bash
# Create API token at: https://id.atlassian.com/manage/api-tokens
# Encode credentials
echo -n "user@example.com:api_token" | base64

# Use in settings
"authorization": "Basic <base64-encoded-string>"
```

**For Jira On-Prem:**

```bash
# Use username:password or PAT
echo -n "username:password" | base64
```

**Check Permissions:**

* User must have read access to projects in JQL
* API token must not be expired

### GitHub Token Invalid

**Error:**

```
Failed to get PRs: 401 - Bad credentials
```

**Cause:** Invalid GitHub personal access token.

**Solution:**

1. Generate new token at <https://github.com/settings/tokens>
2. Required scopes: `repo` (or `public_repo` for public repos only)
3. Update settings:

```bash
export GITHUB_TOKEN="ghp_newtoken..."
```

### Azure DevOps PAT Expired

**Error:**

```
Failed to get the ADO work items: 401 - Unauthorized
```

**Cause:** PAT token expired or invalid.

**Solution:**

1. Generate new PAT in ADO web UI
2. Required permissions:
   * Work Items: Read
   * Extension Data: Read & Write (for plugin)
3. Update authorization:

```bash
echo -n ":your-pat-token" | base64
export ADO_AUTHORIZATION="Basic <base64-result>"
```

***

## Tagging Issues

### No PRs Found

**Error:**

```
No PRs found for repository: frontend-app
```

**Cause:** No PRs in specified time range or repo name mismatch.

**Solution:**

```bash
# Increase time range
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 90

# Verify repo name matches exactly
# Check GitHub UI: https://github.com/<owner>/<repoName>

# Enable debug logging
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 30 --log-level DEBUG
```

### Ticket ID Not Extracted

**Error/Warning:**

```
No ticket ID found in PR title: "Update documentation"
```

**Cause:** Regex pattern doesn't match PR title/commit message.

**Solution:**

Test and fix regex pattern:

```bash
# Example PR title: "[PROJ-123] Add feature"
# Regex: "PROJ-[0-9]+"

# Test regex in Python
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')
"

# Update settings
{
  "scm": {
    "key_pattern_regex": "PROJ-[0-9]+"
  }
}
```

**Common Patterns:**

* Jira: `[A-Z]+-[0-9]+`
* GitHub Issues: `#[0-9]+`
* ADO: `[0-9]+`
* Multiple: `(PROJ|FEAT|BUG)-[0-9]+`

### Git Clone/Pull Failed

**Note:** This only applies if using `US_SRC_tag_repos_by_history.py` (git-based tagging). If using SeaLights auto-tagging or GitHub PR-based tagging, git is not needed.

**Error:**

```
fatal: could not read Username for 'https://github.com': terminal prompts disabled
Permission denied (publickey)
```

**Cause:** Git authentication not configured for repository cloning.

**Solution:**

**For SSH:**

```bash
# Generate key
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Add to ssh-agent
eval $(ssh-agent -s)
ssh-add ~/.ssh/id_rsa

# Add public key to GitHub/GitLab/Bitbucket
cat ~/.ssh/id_rsa.pub

# Test connection
ssh -T git@github.com
```

**For HTTPS with token:**

```bash
# Configure git credential helper
git config --global credential.helper store

# Or use SSH URL in repo_list baseUrl
"baseUrl": "git@github.com:owner/"
```

### App/Branch Not Found in SeaLights

**Error:**

```
Failed to get the branches for app 'my-app' from Sealights: 404
```

**Cause:** Application or branch name doesn't exist in SeaLights.

**Solution:**

```bash
# List apps in SeaLights
# Check exact names (case-sensitive)

# Verify names match in settings
{
  "coverage_app_list": [
    {"app_regex": "exact-app-name", "branch_regex": "exact-branch-name"}
  ],
  "repo_list": [
    {"SealightsAppName": "exact-app-name", "SealightsBranchName": "exact-branch-name"}
  ]
}

# Use regex for flexibility
{"app_regex": "my-app.*", "branch_regex": "main|master"}
```

***

## Report Generation Issues

### No Tickets Found

**Error:**

```
No tickets found, exiting
```

**Cause:** JQL/WIQL returns no results.

**Solution:**

**Test query in web UI:**

* Jira: Issues → Search → Advanced
* ADO: Boards → Queries

```bash
# Broaden query
# Instead of: "created >= -7d"
# Use: "created >= -30d"

# Check project exists
"project = MYPROJ AND created >= -30d"

# Verify API access
curl -H "Authorization: Basic ..." \
  "https://yourcompany.atlassian.net/rest/api/3/search?jql=project=MYPROJ"
```

### Failed to Create Coverage Report

**Error:**

```
Failed to create the coverage report for
Apps/branches: [{'app_regex': 'my-app', 'branch_regex': 'main'}]
```

**Cause:** No builds found matching app/branch in specified time range.

**Solution:**

```bash
# Increase lookback period
{
  "sealights": {
    "coverage_days_back": 30  # Increase from 14
  }
}

# Verify builds exist in SeaLights UI
# Check app/branch names are correct (case-sensitive)

# Enable debug logging
python3 US1_RPT_create_report_info_files.py --settings settings --log-level DEBUG
```

### Report Timeout

**Error:**

```
Coverage report timed out after 30 minutes
```

**Cause:** Report generation taking too long.

**Solution:**

```bash
# Increase timeout
{
  "sealights": {
    "report_timeout_minutes": 60
  }
}

# Or use environment variable
export SEALIGHTS_REPORT_TIMEOUT_MINUTES=60

# Reduce scope
# - Fewer tickets
# - Shorter lookback period
# - Fewer apps/branches
```

### No Coverage Data in Reports

**Symptom:** Reports generated but show 0% coverage for all tickets.

**Cause:** Code hasn't been tagged yet, or ticket IDs don't match tags.

**Solution:**

```bash
# 1. Verify tagging was done
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 30

# 2. Check tags in SeaLights UI
# Navigate to: Build > Tags

# 3. Verify ticket IDs match
# Tag: "PROJ-123"
# Report query: Should return ticket "PROJ-123"

# 4. Ensure coverage_days_back includes tagged builds
```

### Missing ReportInfo Files

**Error:**

```
Found 0 ReportInfo JSON files
```

**Cause:** US1 script didn't run or failed.

**Solution:**

```bash
# Run US1 first
python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira

# Check output folder
ls -la reports/ReportInfo_*.json

# Verify output_folder setting
grep output_folder settings
```

***

## API Issues

### SSL Certificate Verification Failed

**Error:**

```
SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
```

**Cause:** Self-signed certificates or corporate proxy.

**Solution:**

**Temporary (not recommended for production):**

Disable `verify_ssl` only for the platform that is failing. Each platform has its own setting:

```json
{
  "sealights":  { "verify_ssl": false },
  "jira":       { "verify_ssl": false },
  "ado":        { "verify_ssl": false },
  "scm":        { "verify_ssl": false },
  "confluence": { "verify_ssl": false }
}
```

**Proper solution:**

```bash
# Install corporate CA certificate
# 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

# Python requests
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
```

### Rate Limiting

**Error:**

```
Failed to get PRs: 403 - API rate limit exceeded
```

**Cause:** Too many API requests to GitHub/Jira/ADO.

**Solution:**

```bash
# GitHub: Wait for rate limit reset
# Check: curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/rate_limit

# Reduce frequency
# - Process fewer repos at once
# - Increase time between runs
# - Use authenticated requests (higher limits)

# Jira Cloud: Rate limits depend on plan
# ADO: 200 requests per user per hour
```

### Connection Timeout

**Error:**

```
requests.exceptions.ConnectionError: HTTPSConnectionPool: Max retries exceeded
requests.exceptions.Timeout: Read timed out
```

**Cause:** Network issues or slow API.

**Solution:**

```bash
# Check network connectivity
ping github.com
curl https://api.github.com

# Check firewall/proxy settings
# If behind corporate proxy:
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Retry the operation
# Most scripts don't auto-retry on network errors
```

***

## Performance Issues

### Slow Tagging

**Symptom:** Tagging takes hours for large repositories.

**Solution:**

```bash
# Process fewer days
python3 US_SRC_tag_repos_by_github_prs.py --settings settings --days-back 7

# Process repos in parallel (requires GNU parallel)
parallel -j 4 python3 US_SRC_tag_repos_by_github_prs.py --settings settings_{} ::: repo1 repo2 repo3

# Use --only_create_files for testing
python3 US_SRC_tag_repos_by_history.py --settings settings --days-back 7 --only_create_files
```

### Memory Issues

**Symptom:** Script crashes with MemoryError or system becomes unresponsive.

**Solution:**

```bash
# Process fewer tickets at once
# Split JQL query by date ranges

# Reduce child_levels
{
  "jira": {
    "child_levels": 1  # Instead of 3
  }
}

# Process repos individually
# Create separate settings files per repo
```

### Slow Report Generation

**Symptom:** US1 script runs for hours.

**Solution:**

```bash
# Reduce coverage_days_back
{
  "sealights": {
    "coverage_days_back": 7  # Instead of 30
  }
}

# Reduce number of tickets in JQL/WIQL
# Process in batches

# Reuse existing report
python3 US1_RPT_create_report_info_files.py --settings settings --report-id existing-report-id
```

***

## Debugging Tips

### Enable Debug Logging

```bash
python3 US1_RPT_create_report_info_files.py \
  --settings settings \
  --log-level DEBUG \
  2>&1 | tee debug.log
```

### Check API Responses

```bash
# Test SeaLights API
curl -H "Authorization: Bearer $SEALIGHTS_API_TOKEN" \
  "https://company.sealights.co/sl-api/v1/apps"

# Test Jira API
curl -H "Authorization: Basic $JIRA_AUTH" \
  "https://company.atlassian.net/rest/api/3/search?jql=project=MYPROJ"

# Test GitHub API
curl -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/owner/repo/pulls?state=closed&per_page=1"
```

### Validate Configuration

```bash
# Check JSON syntax
python3 -m json.tool settings

# Print resolved settings (with masked secrets)
python3 -c "
import US_common
import logging
logging.basicConfig(level=logging.DEBUG)
settings = US_common.read_settings(['settings'])
"
```

### Test Regex Patterns

```bash
# Test ticket extraction
python3 -c "
import re
text = '[PROJ-123] Add feature'
pattern = r'PROJ-[0-9]+'
match = re.search(pattern, text)
print(f'Found: {match.group()}' if match else 'No match')
"
```

***

## Getting Help

If issues persist:

1. **Check logs** - Review full error messages and stack traces
2. **Verify configuration** - Ensure all required fields are correct
3. **Test APIs directly** - Use curl to test authentication and connectivity
4. **Enable debug mode** - Use `--log-level DEBUG` for detailed output
5. **Check documentation** - Review [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) and [Examples](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md)
6. **Simplify** - Test with minimal configuration first, then add complexity

**Common Root Causes:**

* Authentication/credentials
* Network/firewall/proxy
* Name mismatches (case-sensitive)
* Regex patterns
* Time range too narrow
* Missing data in source systems

***

## Next Steps

* [FAQ](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/faq.md) - Frequently asked questions
* [Configuration](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration.md) - Detailed settings reference
* [Examples](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md) - Working code examples


---

# Agent Instructions: 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:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.