Troubleshooting Templates

Templates in Nuxari are pre-built workflow and control configurations that can be installed into your workspace. Each template runs a preflight check before installation to verify that required connectors, permissions, and dependencies are in place. This guide covers the most common reasons a template installation fails and how to resolve each.

Template installation fails immediately

Symptom:Clicking "Install" on a template returns an error banner immediately — before any preflight checks appear — with a message such as "Installation could not start" or "Template unavailable".

1. 1

   Verify your role allows template installation

   Template installation requires an Admin or Owner role. If you are assigned a lesser role (Auditor, Viewer), the install button may be visible but the API call will be rejected. Ask a workspace admin to install the template or promote your role.

2. 2

   Confirm the template is available in your plan

   Some templates are tier-restricted and are not available on all Nuxari subscription plans. If the template shows as Unavailable with a plan badge, upgrade your subscription or contact Nuxari to request access.

3. 3

   Check if the template is already installed

   A template that is already installed in your workspace cannot be installed again without first removing it. Check the installed templates list to see if the template already exists. If it does, use the reinstall option rather than fresh install.

4. 4

   Retry after a short wait

   If the error message says 'Template service unavailable' or 'Try again later', there may be a transient service issue. Wait 2–5 minutes and retry the installation.

5. 5

   Contact Nuxari support if the error persists

   If the install fails immediately every time with no useful error message, contact support with the template name, your workspace ID, and the exact error text. Include the time of the attempt so the engineering team can review server logs.

Preflight check fails — missing connector

Symptom:The preflight check screen shows a failed item labeled "Required connector not found" or "Connector: [name] is not connected".

1. 1

   Note which connector the preflight check requires

   The preflight failure message names the specific connector. For example: 'Microsoft Entra ID connector not found' or 'GitHub connector is disconnected'.

2. 2

   Go to Integrations and connect the required connector

   Navigate to Integrations (or Connectors) and find the connector named in the error. If it is not present, add it. If it is present but shows as Disconnected, re-authenticate it following the connector-specific instructions.

3. 3

   Verify the connector passes a health check

   After connecting or reconnecting the connector, use the Test Connection button on the connector detail page. Wait for the health check to return a green status before retrying template installation.

4. 4

   Return to the template and retry installation

   Go back to the template in the Control Packs or Templates section and click Install again. The preflight check will re-run. The previously failing connector check should now pass.

Preflight check fails — missing permissions

Symptom:The preflight check identifies a connected connector but reports "Insufficient permissions" or "Required scope not granted".

1. 1

   Review which permissions are required

   The preflight failure detail lists the specific API permissions or scopes the template needs. For example: 'User.Read.All is required but not granted' (Entra ID) or 'repo:read scope is missing' (GitHub).

2. 2

   Update the connector's permissions in the source system

   Log into the source system (e.g., Azure AD app registration, GitHub app settings) and add the missing permissions. For Entra ID, an Azure admin must grant admin consent for new API permissions before they take effect.

3. 3

   Re-authenticate the connector after updating permissions

   After granting new permissions in the source system, return to Nuxari, open the connector, and click Reconnect or Re-authenticate. This forces a new OAuth token to be issued with the updated permission set.

4. 4

   Run a connection test to confirm the new permissions are visible

   After re-authenticating, run Test Connection. Review the permission list shown in the test result to confirm the required scopes are present before retrying template installation.

5. 5

   Retry template installation

   Return to the template and click Install. The preflight permission check should now pass. If it still fails, the permission may require additional time to propagate in the source system — wait 5 minutes and retry.

Template reports API unreachable

Symptom:During preflight or installation, the template reports "API unreachable", "Connection timed out", or "External service returned 503".

1. 1

   Check the status of the external service

   Visit the status page of the relevant external service (e.g., Azure Service Health at status.azure.com, GitHub Status at githubstatus.com). If the service is experiencing an outage, wait for it to recover before retrying.

2. 2

   Test the connector independently

   Go to the connector's detail page in Nuxari and click Test Connection. If the test also fails with a timeout, the connectivity problem is in the connector path, not the template. Troubleshoot the connector first.

3. 3

   Check that the connector credentials have not expired

   Service accounts and OAuth tokens can expire. If the connector was previously healthy but now times out, the underlying credentials may have been revoked or expired. Reconnect the connector with fresh credentials.

4. 4

   Retry installation once the external service recovers

   Once the external service is healthy and the connector test passes, return to the template and retry installation. Transient API timeouts do not permanently block a template — a fresh install attempt will start a new preflight check.

Template already installed but showing as available

Symptom: You are certain a template was installed previously, but the template catalog shows it as Available (not Installed), with an Install button rather than a Manage button.

1. 1

   Confirm you are in the correct workspace

   Templates are installed per workspace. If your organization has multiple workspaces, the template may be installed in a different workspace than the one you are currently viewing. Check the workspace selector in the top navigation.

2. 2

   Check if the template was removed

   A workspace admin may have uninstalled the template. Check the audit log (Audit Log page, filter by event type 'template_removed') to see if a removal event was recorded.

3. 3

   Look for the template in the installed list directly

   In Control Packs or the Templates section, there should be a filter for 'Installed'. If the template appears there, the catalog view may be displaying a stale state. Refresh the page.

4. 4

   Re-install the template if it was genuinely removed

   If the template was removed and needs to be reinstalled, proceed with the Install flow. All previously configured mappings and customizations may need to be reconfigured after reinstallation.

Dependency template required first

Symptom:The preflight check or install flow shows "Required template not installed" or "This template depends on [other template]".

1. 1

   Note the name of the required dependency template

   The error message names the specific template that must be installed first. Copy or note the exact name.

2. 2

   Find and install the dependency template

   Search for the dependency template by name in the template catalog. Install it first, completing its own preflight checks and installation flow.

3. 3

   Return to the original template and retry

   After the dependency template is installed, go back to the template you originally wanted to install and click Install. The preflight check should now pass the dependency validation.

4. 4

   Install dependency templates in the correct order if there are multiple

   Some templates have multiple layers of dependencies. If you see several dependency errors, install the most foundational templates first (those with no dependencies of their own), then work up to the higher-level templates.