Agent Errors

Common issues encountered when running agents in UniSync.

---

Agent Stuck in "Running" State

Symptoms: Agent status shows "running" for more than 10 minutes. No new content appears. The Run Agents page shows a spinner that never resolves.

Cause: The agent process crashed or timed out mid-execution without updating its status. This can happen due to network interruptions, unhandled API errors, or server restarts during a run.

Resolution:

1. UniSync has automatic recovery: any agent cycle stuck in running for more than 10 minutes is automatically marked as failed by the bot status check (_get_bot_status() in seo_intelligence.py).
2. If auto-recovery has not triggered yet, wait a few minutes and refresh the page.
3. If the agent remains stuck after 15 minutes:
   • Check the backend console for error output from the agent's last run.
   • Manually trigger a new run from the Run Agents page -- this will reset the cycle.
4. Investigate the root cause in the logs before re-running, especially if the agent fails repeatedly.

---

Content Generation Failures

Symptoms: Agent runs but produces no content. Logs show errors like 401 Unauthorized, 429 Too Many Requests, or APIError.

Cause: The text generation API key (OpenAI or compatible provider) is invalid, expired, or rate-limited.

Resolution:

1. Go to API Management and verify the text API key is set and valid.
2. Check the provider's dashboard for:
   • Billing status (expired payment method will disable keys).
   • Rate limit usage (you may have hit per-minute or per-day limits).
   • API key permissions (some keys are read-only or restricted).
3. If you see 429 errors, wait a few minutes. UniSync has built-in retry with exponential backoff, but sustained high volume can exhaust retries.
4. Test the key independently:

   curl https://api.openai.com/v1/models \
     -H "Authorization: Bearer YOUR_API_KEY"

5. If the key works externally but fails in UniSync, check that the correct credential is assigned to the publish environment the agent is using.

---

Publishing Failures

WordPress

Symptoms: Content is generated but not published. Logs show 401, 403, or connection errors when posting to WordPress.

Cause: WordPress Application Password is invalid, the site URL is wrong, or the WordPress REST API is blocked.

Resolution:

1. See the full WordPress Connection Troubleshooting guide.
2. Quick checks:
   • Verify the site URL ends without a trailing slash (e.g., https://example.com, not https://example.com/).
   • Confirm the Application Password has not been revoked in WordPress admin.
   • Check that the WordPress user has the publish_posts capability.

Astro Bridge

Symptoms: Content is generated but does not appear on the Astro site. Logs show connection refused or authentication errors.

Cause: The Astro Bridge API is not running, the API key is wrong, or file write permissions are missing.

Resolution:

1. See the full Astro Bridge Troubleshooting guide.
2. Quick checks:
   • Verify the Bridge API URL and port are correct in the environment settings.
   • Confirm the Bridge API process is running on the server.
   • Check the API key matches what the Bridge expects.

---

Queue Not Processing

Symptoms: Posts appear in the SEO Posts Queue with status pending but are never picked up for publishing. No agent activity in logs.

Cause: The scheduler or autopilot is not running, or no agent is assigned to the planner that owns the queued posts.

Resolution:

1. Check if autopilot is enabled for the agent:
   • Go to Run Agents and verify the agent has autopilot turned on with a valid interval.
2. Verify the agent is assigned to the correct planner:
   • An agent must be assigned to the planner whose queue contains the pending posts.
3. Check the agent's interval setting:
   • If set to a long interval (e.g., 24 hours), the agent may simply not have run yet.
4. Check the backend console for scheduler errors.
5. Manually trigger the agent from Run Agents to force immediate processing.

---

Production Agent: Planner Not Ready

Symptoms: Attempting to assign or run a production agent fails with a message like "Planner is not ready" or "Missing: keyword plan / topic cluster / approved strategies."

Cause: The planner linked to the agent is missing one or more required components. All three must be complete before a production agent can run:

1. Keyword Plan -- at least one keyword plan must be linked to the planner.
2. Topic Cluster -- the planner must have a topic cluster defined.
3. Approved Strategies -- content strategies must be generated and approved.

Resolution:

1. Open the planner in the Campaign Planner page.
2. Check each section:
   • Keyword Plan tab: Ensure keywords are added and saved. Maximum 15 keywords.
   • Topic Cluster tab: Ensure a cluster is defined.
   • Content Strategy panel: Click "Generate All" if strategies have not been generated, then "Approve All" (or approve individually) once you have reviewed them.
3. The Assignment Modal shows readiness indicators (green = ready, amber = incomplete). Address any amber items before assigning.
4. After completing all three, return to Run Agents and assign the agent.

---

Quick Publisher: No Automations Assigned

Symptoms: Running a quick publish agent produces no output. The agent completes instantly with zero posts.

Cause: The agent has no automation assignments (search phrases or web sources). Quick publishers rely on automations to know what content to generate.

Resolution:

1. Go to the agent's settings and check the Automations tab.
2. Assign at least one automation:
   • Search Phrase: A keyword or phrase the agent will use to generate content.
   • Web Source: A URL the agent will use as a content source.
3. For each automation, verify the search provider API key is configured (e.g., Google Ads API key for search phrase automations).
4. Re-run the agent after adding automations.