Troubleshooting

Common issues and their solutions. Each guide follows a Problem / Cause / Solution format with step-by-step resolution.

Topics

Guide	Description
Agent Errors	Agents stuck running, content generation failures, publishing errors, and queue issues
WordPress Connection	Application Passwords, SSL errors, REST API access, and timeout problems
Astro Bridge	Bridge API connectivity, authentication, file permissions, and build triggers
API Credentials	Invalid keys, rate limits, quota exhaustion, and provider-specific setup
Token Limits	Token limits per model, cost optimization, rate limit handling, and budget management

General Debugging Tips

1. Check the logs first. The backend console output shows detailed error messages including HTTP status codes and stack traces.
2. Verify your environment. Make sure the correct publish environment is selected and its credentials are valid.
3. Test credentials independently. Use curl or Postman to confirm API keys and endpoints work outside of UniSync.
4. Restart the backend if you have changed .env values -- environment variables are read at startup.
5. Check the database if data looks stale. The Token Analytics dashboard and Agent history can reveal when things last ran successfully.

Still Stuck?

If none of the guides resolve your issue:

• Review the backend console output for the full stack trace.
• Check that your PostgreSQL database is running and accessible.
• Confirm all required environment variables are set in your .env file.
• Search the project repository issues for similar errors.