Xray Cloud Health Check: Diagnose Missing Jira Test Configuration

An Xray panel reports that its health check detected errors upon installation, and the release team cannot continue its planned testing. Reinstalling immediately would change the environment before the administrator has recorded what is missing. Begin with the actual Health Check status, the affected operation, and the configuration evidence needed to choose a repair.

This procedure concerns Xray Cloud, a Jira test-management app. It separates app installation configuration from a tester's access and from inconsistent testing records. A missing panel is an observation; the underlying cause remains a hypothesis until the relevant layer has been checked.

Read the Health Check Status Before Choosing a Fix

Have the Jira administrator inspect Xray's page named Global Settings: Health Check. Record the status and any entity details it exposes. Avoid prescribing a remembered menu path: Jira Cloud labels and administration experiences can differ, and the person viewing a project may not have authority to inspect global configuration.

Xray's Health Check documentation describes checks for Jira entities created or configured when the app is installed or enabled. Its three categories have different operational meanings:

• OK: the checked Xray entities are configured correctly. This does not establish that every user action or test record is healthy.
• Warning: noncritical entities, with issue link types and custom fields given as examples, are missing or incorrectly configured. Panels remain available, but affected features may not work.
• Critical: critical entities, with issue types given as the example, are missing or incorrectly configured. Xray documents panel errors and disabled app features for this state.

There is a wording discrepancy worth preserving. Atlassian's Cloud troubleshooting article discusses a missing link type in its explanation of Critical, whereas Xray uses missing link types as a Warning example. Do not infer severity from the noun alone. Save the status actually reported, the exact entity description, and the symptom; ask Xray support to resolve an unexpected combination rather than rewriting the observation to fit either example.

The check also has a defined boundary. Xray says it does not diagnose inconsistent test status, coverage status, or entity properties inside Xray issues, and points to project reindexing for those inconsistencies. That is a separate investigation. Neither a successful panel load nor a reindex proposal proves that a missing installation entity has been repaired. Obtain current, applicable reindexing guidance before considering that operation.

Separate Configuration Failure From Access Failure

Compare the global observation with the scope of the complaint. Are multiple Xray panels unavailable, or can one tester open a Test Execution but not perform a particular action? Preserve both findings when both occur. A Critical configuration status can coexist with an access problem; fixing one does not establish that the other has disappeared.

Atlassian's article recommends checking global app permissions and the app's Jira-side license as part of this diagnosis. It specifically mentions atlassian-addons-admin. Record what the administrator actually finds, including the relevant app and site, rather than turning the advice into an instruction to grant every permission. A license question, a global installation permission, and project-level access are different checks.

The similarly named atlassian-addons-project-access role belongs to a different layer. Atlassian describes it as a Jira-managed system role for Connect app access, with permitted API actions also constrained by app scopes. Do not treat it as the tester's ordinary membership group or attempt to repair it by adding arbitrary actors. Administrator review should establish the effective permission scheme and app context before proposing a narrowly scoped change.

For a user-specific failure, keep the account, exact work item, and attempted operation fixed. Atlassian's Permission Helper can support native permission diagnosis against a particular work item. It cannot, by itself, establish that an app's workflow restrictions permit execution. A positive administrator check is also not evidence that the affected tester has the same access.

If global entity configuration does not explain the unavailable execution action, continue with the separate Xray Cloud execution permission checks. That workflow distinguishes Browse and Resolve prerequisites from restrictions on the Test and Test Execution states. Do not close a work item, broaden a role, or record a passing result merely to make the symptom disappear.

Build a Missing-Entity Evidence Packet

Capture the initial state before changing configuration. The following fields are a suggested investigation record, not a native Xray export schema or automatically generated support bundle:

• Deployment and app identity: Jira Cloud site reference, installed Xray app name and edition, and whether the complaint concerns an existing installation or a recent installation change.
• Observation: timestamp with time zone, exact visible message, affected panel or action, and whether the observation came from an administrator or the affected tester.
• Configuration finding: actual Health Check status, displayed entity category and name, and identifier where available. Mark unavailable identifiers Unknown instead of inventing them.
• Scope: affected project or space, representative work-item keys, relevant account context, and other contexts actually checked. Separate reported symptoms from reproduced observations.
• Change context: known installation, enablement, permission, link-type, or work-type changes, with their approved change references. An absence of known changes does not prove that no change occurred.
• Open questions: license and access findings, owner of each unresolved check, safe evidence references, proposed next action, and who can approve it.

For link-related findings, preserve more than a display label when the administrator can inspect it safely. Jira link types have a name plus inward and outward descriptions. Atlassian warns that changing link-type names can affect existing JQL results, and deleting a type can involve changing or removing related links. Recreating a familiar label is therefore not a verified restoration procedure. Have support assess the relevant configuration and relationships before proposing deletion or replacement.

Keep screenshots and excerpts small enough to answer a specific question. Remove credentials, session material, unnecessary customer content, and unrelated records before sharing. Confirm that the intended support reviewers can access the approved evidence location. A link in a ticket is not useful evidence if nobody responsible can open it.

For a fuller handoff structure, the Jira bug-report evidence template separates starting conditions, reproduction steps, expectations, observations, and unanswered questions. Use that structure to describe the installation symptom without presenting a suspected missing entity as a proven root cause.

Work Through a Bounded Diagnostic Example

Consider this fictional HC-DEMO-v1 packet. It is an authored teaching example, not an output from a Jira tenant, a real support case, or an executed test. Freeze the starting observations before deciding what they support:

• O1: the supplied administrator note reports Warning and identifies a missing issue link type; its identifier is Unknown.
• O2: the supplied tester note says the Xray panel opens, but associating Test DEMO-12 with requirement DEMO-8 is unavailable; no association was created in the example.
• O3: the supplied access and license checks are Pending, and there is no supplied administrator inventory proving which link type or mapping is absent.
• O4: no reinstall, permission change, entity recreation, or project reindex has been performed; support approval and recovery validation are Pending.

O1 and O2 are compatible with Xray's documented Warning example: panels may remain available while a link-dependent feature is unavailable. Compatibility does not prove why the association action is unavailable. O3 leaves access, licensing, entity identity, and configuration mapping unresolved. Do not upgrade the record to Critical merely because Atlassian's example uses a missing link type in that context.

The proposed next step is an administrator's read-only inventory of the reported entity and the applicable access and license findings, followed by a support review of the mismatch. The packet is not ready for a guessed recreate-by-name operation. O4 also means there is no repair outcome to report. Keep recovery Blocked until the required decision, preservation readiness, and authorized operator are established.

If a later observation instead reports Critical, retain HC-DEMO-v1 and create a separately dated observation. Record the newly reported status and entities without pretending the earlier note already contained them. A changed finding can justify a changed plan, but it cannot establish that an unperformed action succeeded. All actual tenant checks and repair results in this teaching example remain Not Run.

Plan a Support-Reviewed Recovery

Both the Xray Health Check page and Atlassian's matching error article recommend reinstalling the app, with escalation to Xray support if the problem persists. Treat this as documented remediation advice, not evidence that another reinstall will resolve the present site. The pages do not establish the current tenant's root cause, a complete data-preservation contract, or a verified restore path.

Before authorizing a reinstall, send the evidence packet to the administrator and Xray support. Ask which missing or incorrectly configured entities they believe explain the symptom, what operation they recommend for this app and site, and how they will verify the resulting configuration. If the app was already reinstalled, retain that attempt's time and result rather than describing the installation as untouched or repeating it without new reasoning.

Confirm the precise app identity and intended edition. Xray's current installation documentation distinguishes the core Xray app from Xray Enterprise and includes site and edition choices in installation guidance. Its gadget warning concerns specific dual-app or edition-switch situations; it does not establish that every ordinary reinstall loses every gadget configuration. Conversely, a fresh installation walkthrough does not prove preservation of existing testing history.

Agree on the preservation and recovery scope before a mutating operation. Ask the responsible owners which Jira records, app-managed test information, relationships, settings, attachments, and dashboard configurations must remain available. Request the applicable backup, export, retention, and restoration guidance for that scope. Keep unsupported coverage Unknown: a readable export or a general Jira backup is not proof that every app-managed item can be restored.

Separate the person accepting operational risk from the person authorized to implement the repair. The QA lead can describe blocked testing and evidence requirements; the configuration owner and service owner must establish the applicable approval and execution authority. If recovery readiness, access, or the preservation plan remains unresolved, leave the operation Blocked. Do not manufacture a time limit or a safety guarantee to make the plan look executable.

Verify Configuration and the Affected Workflow Separately

After a separately authorized correction, capture a fresh Health Check observation and compare its entity findings with the original record. Verify the intended app and site again. An OK status supports the checked configuration layer; it does not prove historical evidence survived or that the affected account can complete its work.

Agree on a bounded functional validation with the QA and configuration owners. For a link-related complaint, use approved disposable records in the intended testing context and verify both the permitted association and its expected relationship afterward. Have the affected account repeat the relevant operation where authorized. Do not use unrelated production tests or change release results to demonstrate that a panel now renders.

Preserve the original failure, repair reference, subsequent configuration observation, functional result, and any unresolved preservation checks separately. If the panel loads but the required action remains unavailable, continue the access or app-specific branch with that narrower symptom. If configuration remains Critical, provide the new evidence to Xray support rather than declaring success from the installation confirmation alone.

Close the investigation only when the responsible owners accept the checked configuration, the affected workflow, and the agreed preservation evidence. Until then, record the specific remaining blocker. The useful next action is the smallest supportable check or approved repair, with an owner and observable acceptance conditions.