How to resolve errors when migrating projects that result in incomplete deployments or undefined issues

Problem

Users may encounter errors when migrating Jira projects using the Configuration Manager for Jira (CMJ). These errors often result in incomplete deployments or “undefined” errors.

Symptoms

• Deployment fails with an “undefined” error.

• Deployment process reverts changes due to SQL or system configuration issues.

• Errors in audit and debug logs such as:

  • SQL parameter limits:

    SQLServerException: The incoming request has too many parameters. The server supports a maximum of 2100 parameters.

  • Java Heap Memory issues:

    java.lang.OutOfMemoryError: Java heap space

  • Dashboard gadget configuration errors:

    Error while exporting app dashboard gadget configuration data for gadget.

  • Custom field or LDAP errors in the logs:

    CUSTOM FIELD ID 0 OUT OF BOUNDS LdapCtxFactory not found by com.botronsoft.jira.rollout.configuration-manager-core

Root Cause Analysis

1. SQL Parameter Limitation:
   DB management systems limit the number of parameters in an SQL query. This issue can be triggered by large organizations (e.g., over 2100 members).

2. Insufficient Heap Memory:
   Jira instances running with insufficient Java Heap memory (e.g., 2GB) fail during resource-intensive operations like large-scale project migrations.

3. Dashboard Configuration Issues:
   Gadgets from external apps or corrupt configurations cause integrity issues.

4. System Setting Inconsistencies:
   Differences in language, time zone, or system settings between source and target Jira environments can lead to deployment failures.

5. Debug Information Insufficient:
   Lack of debug logs or incomplete support files delays root cause identification.

Resolution Steps

Pre-Migration Checks

1. Run the Integrity Check tool: Integrity Check Documentation.

2. Ensure consistent Jira versions and plugins between source and target instances.

Increase Memory Allocation

1. Increase the Java Heap size to at least 4GB:
   How to Increase Jira Application Memory.

2. Restart the Jira instance after making these changes.

Address SQL Limitations

1. Divide large organizations (>2100 members) into smaller groups before migration.

2. Reference database queries to identify affected organizations:

   SELECT "USER_KEY" FROM "AO_54307E_ORGANIZATION_MEMBER" WHERE "ORGANIZATION_ID" = <org_id>

3. Database Query Example

   SELECT "ORGANIZATION_ID", COUNT("USER_KEY") AS "USER_COUNT" FROM "AO_54307E_ORGANIZATION_MEMBER" GROUP BY "ORGANIZATION_ID" HAVING COUNT("USER_KEY") > 2100;

Resolve Dashboard Issues

1. Run native Jira Integrity Checks and re-index the Jira instance:

   • Navigate to Jira Administration > System > Integrity Check.

   • Perform a Full Re-index.

2. Remove or reconfigure problematic gadgets identified in the logs.

Adjust System Settings

1. Ensure consistent time zone, language, and locale settings between source and target Jira environments.

Logs for Further Analysis

Enable Debug Logs for Further Analysis

1. Enable Debug Logging: Debug Logging Documentation.

2. Attempt the deployment again and collect the updated logs.

3. Include Audit Logs from CMJ: Audit Logging Documentation.

4. Share the complete support.zip file: Creating a Support Zip.

Conclusion

Migrating Jira projects using Configuration Manager for Jira(CMJ) can encounter various errors due to system resource limits, database constraints, or inconsistencies. Following the outlined steps, including increasing memory, addressing SQL limitations, and ensuring consistent system settings, can resolve most deployment issues. For unresolved errors, enabling debug logs and providing detailed support files is essential for further investigation.

For best practices, refer to:

• Best Practices for Configuration Manager for Jira.

Need Further Assistance?
Contact us with logs and error details to resolve your issue efficiently.