Troubleshooting

Overview

This page covers the most frequently encountered issues in AEO Optima and how to resolve them. If your issue is not listed here, contact your organization administrator or reach out to platform support for assistance.

---

Common Issues

---

Detailed Troubleshooting

"Please select a project first"

This message appears when you navigate to a feature page without an active project selected. AEO Optima requires a project context for most operations because prompts, snapshots, and analytics are all scoped to a specific project.

How to fix:

1. Look at the sidebar for the project selector dropdown
2. Click it and choose a project from the list
3. If no projects are listed, you may need to create one under Settings or complete the onboarding setup wizard

Tip: After selecting a project, AEO Optima remembers your selection for future sessions. You should only need to do this once unless you are switching between multiple projects.

---

Dashboard Shows All Zeros

The Dashboard displays metrics calculated from your snapshot data. If you have not captured any snapshots yet, all metric cards will show zero values.

How to fix:

1. Navigate to Snapshots in the sidebar
2. Click New Snapshot
3. Select your prompts and at least one AI model
4. Click Capture and wait for the process to complete
5. Return to the Dashboard — your metrics will now reflect the captured data

If you have captured snapshots but the Dashboard still shows zeros, verify that the correct project is selected in the sidebar.

---

Snapshot Capture Fails

Snapshot failures can occur for several reasons. Work through these checks in order:

1. LLM Configuration — Go to Settings > LLM Configuration and verify that at least one model is enabled. A snapshot cannot run without an active model.
2. API Key Validity — If you are using BYOK, go to Settings > API Keys and verify that your key is correct and has not expired. Some providers invalidate keys after a period of inactivity.
3. Quota or Rate Limits — Some API providers impose rate limits or usage quotas. If your key has exceeded its limits, the capture will fail. Check your provider's dashboard for usage details.
4. Prompt Count — Very large prompt batches combined with multiple models can occasionally time out. Try capturing with fewer prompts to isolate the issue.

Tip: If using BYOK, check that your OpenRouter or provider account has sufficient credits. Add credits to avoid rate limiting.

---

Scheduled Captures Not Running

Automated schedules depend on several components working together. If your scheduled captures are not running:

1. Check Schedule Status — Open the Schedules page and confirm the schedule is set to Active, not Paused.
2. Review Run History — Look at the recent run history for error messages. Failed runs typically include a reason for the failure.
3. Verify LLM Configuration — Schedules use the same LLM configuration as manual captures. If no models are enabled, scheduled captures will fail silently.
4. Check Time Zone — Schedules run based on UTC time. Verify that your expected run time aligns with the UTC schedule you configured.
5. Check Job Status — Jobs stuck in "pending" or "running" for more than 15 minutes are automatically marked as failed. Check if there are stuck jobs blocking new runs.

---

Page Analysis Shows Timeout

The Page Optimization tool fetches and analyzes web pages in real time. Timeouts can occur when:

• The target website is slow to respond
• The website blocks automated requests (bot protection, CAPTCHA, IP restrictions)
• The page is exceptionally large or resource-heavy

How to fix:

1. Try a specific inner page instead of the homepage (e.g., /about, /features, /pricing)
2. Verify that the URL is publicly accessible (not behind a login wall)
3. Check that the URL is correctly formatted (include https://)
4. If the site uses aggressive bot protection, the analysis may not be possible for that particular URL

---

Invitation Not Visible

AEO Optima uses an in-app invitation system. Invitations appear in two locations:

1. Dashboard Banner — A notification banner at the top of the Dashboard showing pending invitations with Accept and Decline buttons. This is visible on every Dashboard page load.
2. Onboarding Page — If you are a new user who hasn't completed onboarding, invitations also appear on the Onboarding page.

If you don't see an invitation:

• Verify you signed up or logged in with the exact email address that was used for the invitation
• Check that the invitation hasn't expired (invitations expire after 7 days)
• Ask the person who sent the invitation to verify the email address and resend if needed
• Try refreshing the page — the invitation banner fetches pending invitations on page load

Tip: Tell your invitee to share the AEO Optima URL with you. Sign up using the same email they invited, then check your Dashboard for the invitation banner.

---

Health Check Shows Unexpected Alerts

The platform's health monitoring uses schedule-aware thresholds that adapt based on your shortest active schedule frequency. For example:

• If your shortest schedule is daily, the system won't flag worker inactivity until 36+ hours have passed
• If your shortest schedule is weekly, gaps of several days are expected and won't trigger alerts

If you see unexpected alerts:

1. Check the Health Reports page (Admin > Platform > Health) for details on each check
2. Verify that your schedules are set to the correct frequency
3. Check if the worker and cron services are running (these are background processes)
4. Review model sync status — if models haven't synced in 48+ hours, the model sync cron may need attention

---

Still Need Help?

If your issue is not covered on this page:

1. Contact your organization administrator — They may have additional context about your organization's configuration.
2. Check the Best Practices guide — Many issues can be prevented by following recommended setup patterns.
3. Review the Quick Start Guide — If you are new to the platform, the setup guide covers the essential configuration steps.
4. Reach out to platform support — For issues that cannot be resolved through the steps above, contact the AEO Optima support team for assistance.