Troubleshooting

When something does not sync as expected, check this page first.

The Troubleshooting tab

Open Hooq from the Apps menu (administrators only), open the Hooq, then select the Troubleshooting tab.

The Troubleshooting tab.

The table lists recent errors with the columns Error, Occurred in (the work item), Triggered by and Time. A line above it says how many are displayed.
Search filters by text, Error filters by kind of error. Select the Search button to apply them and Reset to clear them. If the list looks empty or old, select Search.
The Project box is shown but filtering by project does not work yet. Use Search and Error.
The ... menu above the table has Refresh, Clear All Errors and Create support ZIP.
Tick entries and select Clear Errors to remove ones you have dealt with.
The header of the Hooq page shows how many errors there are (Sync Health).

The ... menu in the header of a Hooq has five items: Resync, Download Hooq work items, Reset sync health, Documentation and Create support ZIP. See The Hooq tab and the header.

Resend a work item (Resync)

Open the work item in Jira.
In the Hooq - Work Sync Panel, select Resync.
Wait for the message Resync completed.

Resync sends the current fields, status, comments and attachments again. It does not create a copy for a work item that has none. For many work items, use Resync from the Hooq header menu. See Resync.

Hooq also retries some failed creates, comments and attachments by itself a few times. Other failures are not retried; use Resync once you have fixed the cause.

Attachment not copied: file too large

What you see: Attachment not copied: <file name> (<size>) is larger than the cross-instance limit of 3.5 MB on <work item>. in the Troubleshooting tab.

What it means: Between two different sites a file can be up to about 3.5 MB. The rest of the work item synced.

What to do: Attach the file to the other work item by hand, or make it smaller and upload it again. On one site there is no Hooq limit. See How to handle a file larger than 3.5 MB.

Update skipped: link missing

What you see: Issue update skipped: link missing on <work item>. Similar lines exist for comments, attachments and status changes (for example Comment skipped: link missing on ...).

What it means: Hooq does not know a partner for this work item, so it skipped the update. This is normal for a work item that was created before the Hooq started, or that does not match the Hooq's limit. It can also mean that a copy was not fully created.

What to do: Open the work item and look at the panel. If it says This issue is not Hooqed, the work item is not part of the Hooq. If you expected it to be, tell your administrator and give the work item key.

The copy's status does not follow (no workflow mapping)

What you see: The status of the original changes but the copy stays where it was. Hooq records the warning Transition skipped ...: no workflow mapping covers source status "<status>". Warnings are not shown in the Troubleshooting tab, so the missing status is usually found by comparing the two projects.

What it means: The status of the original is not matched to any status in the other project.

What to do:

Open the Hooq and go to Configuration, then the Workflows tab.
Add a match for the missing status.
Publish the configuration.
Change the status again, or use Resync on the work item.

The warning text says Workflow tab. In the app the tab is called Workflows.

A file or comment was deleted and the other side still has it

This is by design while Prevent Attachment Deletion and Prevent Comment Deletion are on in the Advanced tab. Deleting an attachment that is already gone on the other side does no harm.

A work item was deleted or moved

Hooq never deletes the other work item. Its panel shows a red message (The hooqed work item has been deleted. or ...has been moved.) and This work item is no more hooqed. The buttons are hidden. This is expected.

Syncs are slow or delayed

Under heavy load, Jira and Forge limit how fast an app can work, and a change can arrive late. In the Troubleshooting tab the Error filter has the value Rate limit for such entries (for example Request rate limited). Wait a few minutes. If a work item still has not arrived after that, use Resync.

Hooq status shows Paused or Stopped

A paused or stopped Hooq does not sync. Start it again from the Hooq page. If a license message appears, ask your site administrator to check the Hooq license. If the header shows STOPPED just after you started, reload the page: it can be out of date for a few seconds.

The panel shows Unable to load Hooq status for this issue

What you see: a red message in the panel instead of the rows.

What it means: the panel could not read the status. This is usually short-lived.

What to do: wait. The panel tries again by itself and waits longer after repeated failures. Reload the work item if it stays this way, and tell your administrator.

Hooq dashboard shows: Hooq dashboard data is available to Jira administrators.

What it means: the Hooq dashboard gadget is for Jira administrators only for now. This is expected for other users. Ask a Jira administrator.

Contact support

Select Create support ZIP in the Troubleshooting tab menu or in the header menu, note the work item key and what you did, and send both to support.