In this short guide, you'll see how to fix TypeError when searching Jira issues after migration to REST API v3.

Here you can find the short answer:

(1) Update to latest jira library

pip install jira --upgrade

(2) Use expand parameter correctly

issues = jira.search_issues('project=PROJ', expand='changelog,renderedFields')

(3) Handle maxResults parameter

issues = jira.search_issues('project=PROJ', maxResults=50)

So let's see how to resolve common TypeError issues when working with Jira REST API v3 in Python.

Problem: TypeError After API v3 Migration

After Atlassian migrated from REST API v2 to v3, many Python scripts started throwing errors like:

TypeError: search_issues() got an unexpected keyword argument 'expand'
TypeError: 'NoneType' object is not iterable

This breaks existing automation scripts, CI/CD pipelines, and reporting tools that rely on the Jira Python library.

1: Update Jira Python Library

The primary fix is updating the jira Python library to version 3.5.0+ which supports REST API v3:

from jira import JIRA

jira = JIRA(
    server='https://your-domain.atlassian.net',
    basic_auth=('[email protected]', 'api_token')
)

jql = 'project = PROJ AND status = "In Progress"'
issues = jira.search_issues(jql, maxResults=50)

print(f"Found {len(issues)} issues")
for issue in issues:
    print(f"{issue.key}: {issue.fields.summary}")

result:

Found 12 issues
PROJ-101: Implement user authentication
PROJ-102: Fix database connection bug
PROJ-103: Update API documentation

Key changes in v3:

  • Authentication uses API tokens instead of passwords
  • expand parameter syntax changed
  • maxResults default changed from unlimited to 50

2: Handle Expand Parameter Correctly

The expand parameter in API v3 requires specific field names. Common errors occur when using old v2 syntax:

from jira import JIRA

jira = JIRA(
    server='https://your-domain.atlassian.net',
    basic_auth=('[email protected]', 'api_token')
)

jql = 'project = PROJ ORDER BY created DESC'

issues = jira.search_issues(
    jql,
    maxResults=10,
    expand='changelog,renderedFields,names'
)

print("Issue details with expanded fields:")
for issue in issues:
    print(f"\nKey: {issue.key}")
    print(f"Status: {issue.fields.status.name}")
    print(f"Assignee: {issue.fields.assignee.displayName if issue.fields.assignee else 'Unassigned'}")
    
    if hasattr(issue, 'changelog'):
        print(f"Changelog entries: {len(issue.changelog.histories)}")

result:

Issue details with expanded fields:

Key: PROJ-123
Status: In Progress
Assignee: John Smith
Changelog entries: 15

Key: PROJ-124
Status: To Do
Assignee: Sarah Johnson
Changelog entries: 3

Valid expand values for v3:

  • changelog - Issue change history
  • renderedFields - HTML-rendered field values
  • names - Field name mappings
  • schema - Field schema information
  • transitions - Available workflow transitions

3: Handle Pagination with startAt

API v3 enforces maxResults limits (default 50, max 100). For large result sets, use pagination:

from jira import JIRA

jira = JIRA(
    server='https://your-domain.atlassian.net',
    basic_auth=('[email protected]', 'api_token')
)

jql = 'project = PROJ'
all_issues = []
start_at = 0
max_results = 50

while True:
    issues = jira.search_issues(
        jql,
        startAt=start_at,
        maxResults=max_results
    )
    
    all_issues.extend(issues)
    print(f"Retrieved {len(issues)} issues (total: {len(all_issues)})")
    
    if len(issues) < max_results:
        break
    
    start_at += max_results

print(f"\nTotal issues retrieved: {len(all_issues)}")

result:

Retrieved 50 issues (total: 50)
Retrieved 50 issues (total: 100)
Retrieved 50 issues (total: 150)
Retrieved 23 issues (total: 173)

Total issues retrieved: 173

This ensures you retrieve all matching issues without hitting API limits.

Common Errors and Solutions

Error: TypeError: 'NoneType' object is not iterable

Solution: Check if search_issues() returns None due to authentication failure:

if issues is None:
    print("Authentication failed or no issues found")
else:
    for issue in issues:
        print(issue.key)

Error: expand parameter not working

Solution: Ensure you're using correct v3 expand values. The old editmeta and metadata are no longer valid.

Error: maxResults exceeded

Solution: API v3 enforces maximum of 100 results per request. Use pagination for larger datasets.

Migration Checklist

  • Update jira library to 3.5.0+: pip install jira --upgrade
  • Use API tokens instead of passwords for authentication
  • Update expand values to v3-compatible options
  • Add maxResults parameter (default changed from unlimited to 50)
  • Implement pagination for queries returning 50+ results
  • Test all JQL queries - some v2 syntax is deprecated
  • Handle None results - add null checks for robustness

Resources