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

Vivid Trace 1.3 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. This document covers the following topics:

How to Interpret Message Codes

Vivid Trace issues message codes to communicate about error and warning situations. The format of the codes can help you understand the nature of the code.

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".

Message Reference

The messages documented here are indexed by message code, listed in alpha-numeric order. They explain the conditions that resulted in the message and what actions can be taken to remediate the situation. 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.

Error Messages

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

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.

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 for each of JIRA and Vivid Trace is mismatched.

Remedial Action: As a JIRA administrator, view the Vivid Trace entry in Add-On Management in JIRA Administration and configure it with the License Key from a valid Vivid Trace license.

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

Unknown item: ID

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 browse 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 supplier 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 supplier 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 supplier or from the Atlassian Marketplace.

Warning Messages

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, and may change in content on consecutive searches.

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 search process found related issues for which the user account executing the search doesn't have browse permission. The search 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.

Remedial Action: The search results are correct to 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 an incomplete view of the results due to insufficient permissions. For some information on how partial results can impact decision making, see Security and JIRA Permissions in the Search and JQL Reference documentation.

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 supplier or Vivid Support for assistance. If you obtained the license from your supplier, 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 supplier or from the Atlassian Marketplace.