Troubleshooting

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

Table of Contents

• Installation Issues

• Configuration Issues

• Authentication Issues

• Tagging Issues

• Report Generation Issues

• API 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:

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:

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

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

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

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

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

{
  "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:

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:

# Create API token at: https://id.atlassian.com/manage/api-tokens
# Encode credentials
echo -n "[email protected]:api_token" | base64

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

For Jira On-Prem:

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

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:

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:

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

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

# Generate key
ssh-keygen -t rsa -b 4096 -C "[email protected]"

# 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 [email protected]

For HTTPS with token:

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

# Or use SSH URL in repo_list baseUrl
"baseUrl": "[email protected]: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:

# 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

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

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

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

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

# 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):

{
  "sealights": {
    "verify_ssl": false
  }
}

Proper solution:

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

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

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

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

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

# 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

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

Check API Responses

# 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

# 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

# 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 and Examples

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 - Frequently asked questions

• Configuration - Detailed settings reference

• Examples - Working code examples