Documentation Troubleshooting

Troubleshooting Guide

Common issues and recommended solutions to get you back on track.

1. Sync-o didn't update my page

Symptoms: Ticket moved to "Done", but no update appeared on Confluence.

Possible Causes:

  • No Link: The Jira ticket description did not contain a link to a Confluence page.
  • Permissions: The Sync-o app user doesn't have edit permission on that specific Confluence page/space.
  • Irrelevant: The AI deemed the ticket "Not Relevant" (Confidence Score = 0).

Steps to Fix:

  1. Check Links: Ensure the full URL to the Confluence page is present in the Jira ticket description or comments.
  2. Check Logs: Look for a comment on the Jira ticket (Sync-o adds a comment after processing). If none exists, check if the app is active in Jira settings.
  3. Check Permissions: Verify that "Apps" or the Sync-o user has "Add/Edit" permission in the Confluence Space settings.

2. Updates are always saved as Drafts

Symptoms: You see comments saying "Draft Created" but nothing is published automatically.

Cause: Your Auto-Publish Threshold is set too high, or the AI is not confident enough in the changes.

Steps to Fix:

  1. Go to Sync-o Settings → Quality Control.
  2. Lower the threshold (e.g., try 80% or 75%).
  3. Review the draft manually to see why the AI was hesitant (usually ambiguous ticket info).

3. "BYOM Verification Failed"

Cause: Invalid API Key, expired credits, or network restrictions.

Steps to Fix:

  1. Regenerate a new key from your provider (OpenAI, Anthropic, or Google — via Google Cloud Console or Google AI Studio).
  2. Check your billing status with the provider.
  3. Ensure no firewalls block outbound requests to api.openai.com, api.anthropic.com, or generativelanguage.googleapis.com.

4. Smart Hub shows "Upgrade to Advanced"

Cause: Your license is Standard Edition; Smart Hub requires Advanced Edition.

Steps to Fix:

  1. Upgrade to Advanced Edition via the Atlassian Marketplace.
  2. Once upgraded, the Smart Hub will be fully accessible.
Note: Standard Edition includes automatic doc updates on ticket completion - you don't need Smart Hub for the core automation to work.

5. Ticket marked "Done" before configuring Sync-o

Symptoms: You moved a ticket to "Done" but Sync-o didn't process it because the Smart Hub sidebar was never configured for that ticket (no Confluence pages linked, no scan run).

Cause: Sync-o triggers when a ticket transitions to "Done". If the Smart Hub hasn't been configured for the ticket yet — no linked Confluence pages, no documentation targets — Sync-o has nothing to update. The transition is consumed and won't re-fire on its own.

Steps to Fix:

  1. Move the ticket back to "To Do": In Jira, transition the ticket from "Done" back to "To Do" (or your board's initial status). This resets the workflow so Sync-o can pick up the transition again.
  2. Configure Sync-o in the sidebar: Open the ticket and look for the Smart Hub glance in the right-hand panel. From there, link the relevant Confluence pages, run a Related Issue Scan, or use Create Documentation to generate a new page.
  3. Move the ticket to "Done" again: Once your documentation targets are in place, transition the ticket back to "Done". Sync-o will now process the update as expected.
Tip: To avoid this in the future, use the "Complete with Sync-o" action from the ticket's More Actions (⋮) menu instead of manually moving the ticket. It automatically scans for documentation before completing the ticket. See Enterprise Features for details.
Back to Documentation Contact Support