Documentation for non-current version Vivid Trace 1.4.
See documentation for the current release Vivid Trace 2021.1

Vivid Trace 1.4 Messages and Codes

This document details the error and warning messages and their codes issued by Vivid Trace. Messages are indexed by message code and explain the conditions that resulted in the message and what actions can be taken to remediate the situation. Entries are listed by message code in alpha-numeric order. This document covers the following topics:

How to Interpret Message Entries

The italicized phrases in the message text correspond to the execution context of the message, user input, or information useful to quick remediation. Once a message code is assigned, the meaning of the message & code will not change in future releases, and will not be reutilized with a different meaning, even as it may eventually be retired.

VT

E

W

-

number

Vivid Trace

Message type discriminator:
Error or Warning

Unpadded serial number

Message Code Format. Error messages are assigned codes that follow the pattern VTE-12, which in this example means "Vivid Trace error #12". Warning messages are assigned codes that follow the pattern VTW-34, which in this example means "Vivid Trace warning #34".

Error Message Reference

VTE-1
error

Function JQL-function could not find item: item-list.

Explanation: The items in item-list were not found.

Remedial Action: Confirm that each item in item-list exists, that the items are specified correctly in the function parameters, and that the user account executing JQL-function has permission to browse those items as applicable.

VTE-2
error

Function JQL-function doesn't accept the identifier parameter, which is already set to the equivalent of value.

Explanation: JQL-function doesn't accept the parameter identifier. Conceptually, JQL-function behaves as though it already has a parameter identifier whose value is set to value.

Remedial Action: Remove the identifier parameter from the function parameters in the JQL query. Reassess the usage of JQL-function.

VTE-3
error

Incorrect usage of function JQL-function. Usage: usage

Explanation: Parameters are being used incorrectly for function JQL-function.

Remedial Action: Correct the parameter(s) according to usage. Consult the documentation for detailed information on correct usage of JQL-function and its parameters.

VTE-6
error

Function JQL-function: In JQL query JQL-query: error-message

Explanation: JQL-function attempted to execute JQL-query in order to gather seed issues from its results, but Jira could not process JQL-query and issued error-message instead.

Remedial Action: Handle the error stated in error-message. You may be able to isolate the cause of the JQL error by executing JQL-query directly in a Jira Advanced Search.

VTE-7
error

Function JQL-function: The identifier parameter can be supplied at most once.

Explanation: Although JQL-function accepts at most one instance of the identifier parameter, more than one occurrence of the parameter is being supplied to JQL-function.

Remedial Action: Modify JQL-function's parameter list to have at most one identifier parameter. Consult the documentation for detailed information on correct usage of identifier.

VTE-8
error

Function JQL-function: More than one issue link type matches the text text: matches

Explanation: The issueLinkType parameter can indicate a specific issue link type based on any of its name, inward description, or outward description, as long it uniquely matches one issue link type. text matched multiple issue link types listed in matches and is therefore ambiguous.

Remedial Action: Modify the issueLinkType parameter to specify a name, inward description, or outward description that unambiguously identifies one issue link type. Also, consider disambiguating the issue link types listed in matches by adjusting their names, inward descriptions, and outward descriptions from within Jira Administration.

VTE-9
error
This message was migrated to VTW-16 in Vivid Trace version 1.4.1.
VTE-10
error

Function JQL-function: The identifier parameter must specify at least one effective direction.

Explanation: After calculating the effective directions based on parameter identifier's value, the effective directions is empty and is therefore not usable to JQL-function.

Remedial Action: Modify the identifier parameter to yield at least one effective direction.

VTE-11
error

Function JQL-function: The identifier parameter must be an integer number between minimum and maximum, inclusive.

Explanation: The numeric value of parameter identifier is not within the acceptable range of minimum and maximum.

Remedial Action: Modify parameter identifier's value to be a number no lower than minimum and no higher than maximum.

VTE-12
error

Function JQL-function: Could not get search results for item: error-message

Explanation: item could not be processed. error-message might indicate the cause.

Remedial Action: Handle the error stated in error-message.

VTE-13
error

Function JQL-function requires seed issues, supplied using the "issue" and/or "jql" parameters.

Explanation: JQL-function requires seed issues, but none were supplied.

Remedial Action: Supply seed issues to JQL-function by specifying at least one issue and/or jql parameter.

VTE-14
error

Function JQL-function: The identifier parameter cannot be empty. Usage: usage

Explanation: Parameter identifier requires a value but was not supplied one.

Remedial Action: Set a value for parameter identifier according to usage.

VTE-15
error

Function JQL-function: Syntax error at character n of identifier parameter. Usage: usage

Explanation: There is a syntactic error in parameter identifier, starting at character number n.

Remedial Action: Correct parameter identifier according to usage.

VTE-16
error

Vivid Trace cannot be used while its custom field is damaged or missing. Please contact your Jira administrators to restore functionality.

Note: The wording of this message varies depending on context.

Explanation: The custom field VTDirections required by Vivid Trace cannot be used while its custom field is damaged or missing.

Remedial Action: To restore functionality, please ensure the custom field "custom-field" is removed if possible, disable then re-enable the Vivid Trace add-on or alternatively restart Jira, and then perform a re-index before resuming use of Vivid Trace.

VTE-17
error

Please contact your Jira administrators to configure Vivid Trace with a valid license.

Note: The wording of this message varies depending on context.

Explanation: Vivid Trace is not configured with a valid license. It is possible that Vivid Trace has yet to be configured with a license, that the configured license has expired, or that the number of licensed users in the Vivid Trace license doesn't match or exceed Jira's licensed user tier.

Remedial Action: As a Jira administrator, license Vivid Trace with a license that is valid for your Jira system.

VTE-19
error

An internal error occurred. For support, please report the following information to Vivid Support: information

Explanation: A condition in Vivid Trace or elsewhere within Jira that prevents successful processing has occurred.

Remedial Action: If the condition doesn't appear to be immediately user serviceable, contact Vivid Support and include information in your support request.

VTE-20
error

Either item ID doesn't exist or you don't have permission to access it.

Explanation: A non-existent item with ID ID was requested.

Remedial Action: Ensure that ID is correct and that the user account requesting item has permission to access it.

VTE-21
error

That license key was malformed and could not be applied. Ensure that the entire Vivid Trace add-on license key is entered exactly as provided. For assistance, contact your supplier or Vivid Support.

Explanation: An attempt was made to update Vivid Trace with an incorrectly-formed license key, which occurs when the license key text has been altered. The license could not be interpreted and therefore no change was made to Vivid Trace's licensing status within Jira.

Remedial Action: Update Vivid Trace with the license key, taking care to copy & paste (or otherwise input) the license key material directly and in whole as you had received it, without any character conversion, and with no stray characters in the license key field. If indeed the license key is unusable, please contact your Partner or Vivid Support. Whitespace, such as spaces and newlines, has no impact on the correctness of the license key.

VTE-22
error

License is for an older version of Vivid Trace and maintenance has expired.

Explanation: Vivid Trace uses Atlassian's Purchasing & Licensing model, where a license is usable with any version of Vivid Trace whose release date is on or before the maintenance expiry date of the license. Versions of Vivid Trace released after the license's maintenance expiry date cannot be used in conjunction with the license. This situation can arise when updating Vivid Trace to a newer version in your Jira system after your maintenance contract has lapsed.

Remedial Action: Apply a license whose maintenance expiry date comes on or after the release date of your version of Vivid Trace. A new license can be obtained from your Partner or from the Atlassian Marketplace. Note that downgrading to an older release of Vivid Trace suitable for use with the license may lead to undefined & unsupported behavior.

VTE-23
error

License is incompatible with number of users in Jira license.

Explanation: Vivid Trace uses the Atlassian Marketplace Licensing and Pricing system, where the number of users in the Vivid Trace license must meet or exceed the number of users licensed for your Jira system. This situation can arise when upgrading your Jira Server license to a higher user tier.

Remedial Action: Obtain a Vivid Trace license whose number of users matches or exceeds your Jira license user tier, and apply it to Vivid Trace. A new license can be obtained from your Partner or from the Atlassian Marketplace.

VTE-24
error

Jira could not be contacted.

Explanation: The Vivid Trace software in the web browser received an error while attempting to contact Jira. The UI now indicates settings that may be inconsistent with the actual, unchanged settings stored in Jira. If you were attempting to save changes, those changes may be lost.

Remedial Action: Confirm that Jira is available on the network, that the web browser can connect to Jira, and that the user is adequately logged-in and permitted to access the resource or perform the operation, then refresh the page to reattempt the operation from a starting point that is consistent with settings in Jira.

VTE-26
error

This operation can only be performed while authenticated. Please log in and try again.

Explanation: You attempted to access a protected resource or perform a privileged operation without being logged in.

Remedial Action: Log in and then try again.

VTE-27
error

Malformed request: info

Explanation: This message can result from directly interacting with the Vivid Trace REST API by sending a request with syntax errors, using incorrect data types, or whose structure is unrecognized by Vivid Trace.

Remedial Action: Remediate the problem as indicated by info.

VTE-28
error

Access denied. Please contact your Jira administrators for permission.

Explanation: You attempted to access a resource without sufficient permission. This message can occur when the web browser was left open for a while and the user was automatically signed out or their access permissions were altered.

Remedial Action: Confirm that you're adequately logged in and permitted to access the resource, then refresh the page and reattempt access to the resource.

Warning Message Reference

VTW-1
warning

Function JQL-function is making use of issue link relationship information while Jira's Issue Linking feature is deactivated. Results might be incorrect.

Explanation: Jira doesn't specify how it responds to requests for issue link information while its Issue Linking feature is deactivated. For this reason, Vivid Trace cannot provide guarantees about whether JQL-function's results are accurate or not.

Remedial Action: Either scrutinize JQL-function's results, or re-assess JQL-function's need to use issue link relationship information. Alternatively, activate the Issue Linking feature within Jira Administration.

VTW-2
warning

Function JQL-function is making use of parent and sub-task relationship information while Jira's Sub-tasks feature is deactivated. Results might be incorrect.

Explanation: Jira doesn't specify how it responds to requests for sub-task information while its Sub-tasks feature is deactivated. For this reason, Vivid Trace cannot provide guarantees about whether JQL-function's results are accurate or not.

Remedial Action: Either scrutinize JQL-function's results, or re-assess JQL-function's need to use sub-task relationship information. Alternatively, activate the Sub-tasks feature within Jira Administration.

VTW-4
warning

Function JQL-function: No seed issues were found.

Explanation: After JQL-function computed the seed issues, the resulting set of aggregated seed issues was empty. JQL-function produces results based on seed issues, and without seed issues it correctly returned an empty result set accompanied by this warning.

Remedial Action: Depending on the nature of the supplied seed issues and the execution context, including what permissions the executing account has to those seed issues, you might be expecting this result. If not, investigate the seed issue parameters, including their correctness, and browse permissions on the expected set of seed issues relative to the user account that issued the JQL query.

VTW-5
warning

Function JQL-function: Issue link types were set even though the effective directions effective-directions don't include issue links.

Explanation: Issue link types are explicitly supplied to JQL-function using the issueLinkType parameter, but JQL-function is not instructed to follow the issue link directions inward and/or outward as listed in effective-directions. One way to encounter this warning is over the natural course of evolving JQL queries, for example by changing the JQL function from relatesWith(), which follows issue links, to parents(), which doesn't.

Remedial Action: Eliminate the issueLinkType parameter from JQL-function's parameter list.

VTW-6
warning

Limiting quantity of displayed issues to the Issue Count Soft Maximum of maximum.

Explanation: The number of actual resulting issues exceeds maximum, and so the Issue Count Soft Maximum mechanism terminated the search process while its result set contained approximately maximum issues and is returning just those resulting issues. The results represent a portion of the actual results. If consecutive searches also exceed this limit, the results may vary from search to search.

Remedial Action: See Issue Count Soft Maximum for information about this condition.

VTW-7
warning

One or more issues have been omitted due to insufficient browse permissions.

Explanation: The trace process encountered issues for which the user account executing the trace doesn't have browse permission. The trace process abruptly halts itself at each such issue, and instead returns this warning along with the resulting issues to which the account does have sufficient permission that lead up to but don't include the inaccessible issues. Possible causes include project permission settings, issue security settings on individual issues, and security settings for the requesting user account.

Remedial Action: The trace results are correct vis-à-vis the requesting user account provided that the permissions on issues, projects, etc. are correct. This warning reminds the viewer to factor into their decision making that they have a potentially incomplete view of the results due to insufficient permissions. Methods of resolution include:

  • Ignore this warning while maintaining awareness that the results are incomplete,
  • Perform the trace with a Jira user account that has permission to browse all issues in question,
  • Analyze your results for completeness and determine the relevance of the omissions,
  • Investigate and narrow down the identity or characteristics of the inaccessible issues,
  • Adjust the trace configuration, and
  • Adjust BROWSE permission on project permission schemes and issue-level security schemes.
There is further discussion in Security and Jira Permissions in the JQL Reference documentation and in Nuances and Considerations.

VTW-8
warning

Issue Linking is deactivated and is not available to Vivid Trace. Either ignore this warning, or activate Issue Linking in Jira System Administration.

Explanation: Jira doesn't specify how it responds to requests for issue link information while its Issue Linking feature is deactivated. For this reason, Vivid Trace cannot provide guarantees about whether search results, Issue Relation Graphs, etc. are accurate or not. Users should expected to receive warning VTW-1 while Issue Linking is deactivated.

Remedial Action: If users need to use issue linking information in conjunction with Vivid Trace, activate the Issue Linking feature within Jira Administration.

VTW-9
warning

Sub-tasks are deactivated and are not available to Vivid Trace. Either ignore this warning, or activate Sub-tasks in Jira System Administration.

Explanation: Jira doesn't specify how it responds to requests for sub-task information while its Sub-tasks feature is deactivated. For this reason, Vivid Trace cannot provide guarantees about whether search results, Issue Relation Graphs, etc. are accurate or not. Users should expected to receive warning VTW-2 while Sub-tasks are deactivated.

Remedial Action: If users need to use sub-task information in conjunction with Vivid Trace, activate the Sub-tasks feature within Jira Administration.

VTW-11
warning

Function JQL-function: In JQL query JQL-query: warning-message

Explanation: JQL-function received warning-message while executing JQL-query.

Remedial Action: Determine if warning-message has a detrimental impact on the results and whether warning-message should be handled.

VTW-12
warning

Custom field custom-field erroneously represents issue issue as having relation. Does this issue, or Jira, need to be reindexed?

Explanation: One condition that can give rise to this warning is that the custom field custom-field that Vivid Trace uses to track relations with other issues appears to represent issue issue as having the specified relationship relation when in fact it does not. Another condition is that the user is requesting Vivid Trace to make use of either issue link or sub-task information while the respective Jira feature is deactivated.

Remedial Action: The index might be out of sync with issue date for issue, a possibility that can be diagnosed by re-indexing Jira.

VTW-13
warning

The license was successfully updated, but the license is invalid.

Explanation: A correctly-formed license was applied to Vivid Trace, but one or more terms of the license are incompatible with your Jira and Vivid Trace system.

Remedial Action: Inspect license details to determine why the license is invalid. If necessary, contact your Partner or Vivid Support for assistance. If you obtained the license from your Partner, license details are found in Vivid Trace's License Information page within Jira Administration. For licenses issued by the Atlassian Marketplace, license details are found in Vivid Trace's entry in the Universal Plugin Manager.

VTW-14
warning

Maintenance expired on date.

Note: The wording of this message varies depending on context.

Explanation: The active maintenance period of the license applied to Vivid Trace will expire or has expired on date. Maintenance, including support and software updates, are available up to and including the expiry date.

Remedial Action: To continue receiving maintenance beyond date, including support and software updates, apply a new product license to Vivid Trace. A new license can be obtained from your Partner or from the Atlassian Marketplace.

VTW-15
warning

Displaying portion of graph that was discovered within the Graph Traversal Time Limit of seconds seconds.

Note: The wording of this message varies depending on context.

Explanation: The Jira system started performing the work of traversing the graph and accumulating information on issues it found along the way, but for that work to be completed, it would have had to exceed the time limit of seconds, and so the calculation was halted and the intermediate results were used as-is. The results likely represent a portion of the actual results, as once this limit is elapsed, no further searching is conducted. The time limit of seconds is measured according to wall-clock time, and is a timer that elapses according to Jira's notion of the system clock provided by the host operating system to the JVM that Jira runs within, ignoring any other processing that is happening in parallel within the Jira system and in other host processes. Searches are more likely to run slower and hence encounter this limit whenever the Jira system and/or its host are experiencing higher loads.

Remedial Action: Modify the trace to query for fewer issues, conduct the search when the Jira system is less loaded, or simply run the trace again. You can also increase the Graph Traversal Time Limit, or improve Jira system performance.

VTW-16
warning

Function JQL-function: The effective directions is set to follow issue links effective-directions but there are no effective issue link types.

Explanation: JQL-function is instructed to follow the issue link directions inward and/or outward as listed in effective-directions, but either the issueLinkType parameter excludes all issue link types configured in Jira, or there are no issue link types configured in Jira at all. JQL-function is unable to conduct its search by following issue links because there are no effective issue link types.

Remedial Action: If the issueLinkType parameter excludes all available issue link types, modify it so that there is at least one effective issue link type. If there are no issue link types configured in Jira, add issue link types in Jira Administration.