Skip to content
Foundation Docs

Monitor & troubleshoot

Sync Agents usually run silently in the background. When something goes wrong — a missing issue, a long-running job, a rate-limit warning — the Sync Agents section of the Inspector is where you investigate.

Check job status

Section titled “Check job status”
  1. Open the lens and open the Inspector panel.
  2. Expand the Sync Agents section.
  3. The header shows the current state:
    • Idle — no run in progress, last run succeeded.
    • Running — a run is in flight. A spinner and stage name (for example, “Insert”) appear.
    • Warning — the last run completed with issues (truncation, rate-limit caution, permission gaps). Hover for details.
    • Failed — the last run errored out. The message links to a likely cause.

Active jobs poll every 3 seconds. You can close the panel — progress continues in the background.

Common problems and fixes

Section titled “Common problems and fixes”

Issues I expect to see are missing

Section titled “Issues I expect to see are missing”
  • Check the JQL. Paste it into Jira’s JQL editor to confirm it returns the expected issues. A typo or a renamed custom field will silently drop rows.
  • Check viewer permissions. Sync Agents run as the lens owner. Each viewer only sees issues they have Jira BROWSE on — so a viewer without access to project X will see the lens minus those rows.
  • Check Max items. JQL Insert caps at the value you set (default 1000). If your query returns 2,000 issues and you haven’t raised the cap, the extra 1,000 are skipped.

The lens didn’t update after a Jira change

Section titled “The lens didn’t update after a Jira change”
  • Field edits appear within a couple of seconds via Jira events.
  • Structural changes (issue newly matches a JQL query) can take up to 10 seconds.
  • If nothing arrives after a minute, click Refresh data or Run Sync Agents manually.

A run failed with a timeout

Section titled “A run failed with a timeout”

Async event jobs run up to 15 minutes. If you hit the ceiling:

  • Narrow the JQL so fewer issues are returned.
  • Lower the Depth on a Child Extend.
  • Split one broad agent into two narrower ones scoped under different Flex Items.

A rate-limit warning appears

Section titled “A rate-limit warning appears”

The Jira API uses a point budget per hour. When a run gets close to the limit, Foundation pauses the pipeline and shows a caution banner. Wait for the hourly reset, then re-run manually.

Edit or delete an agent

Section titled “Edit or delete an agent”

Inside the Sync Agents section:

  • Click the edit icon on an agent row to change its query, type, or options.
  • Click the delete icon to remove the agent. Issues it brought in are removed from the tree on the next run unless another agent also matches them.
Section titled “Related”