Troubleshooting

Troubleshoot common Playbook setup and run issues

Use this guide when a Playbook produces poor output, stalls, routes review incorrectly, or uses the wrong version.

Symptom	Likely cause	Solution
Output quality is low	The Brand Kit is stale or uses the legacy format.	Migrate to the new Brand Kit format and audit voice, writing rules, audiences, and regions.
"Brand Kit required" error after attaching a Brand Kit	The Input type is Text instead of Brand Kit.	Open the Input settings and switch the type to Brand Kit.
Playbook misses obvious opportunities	Prompt coverage is incomplete or stale.	Audit tracked Prompts and expand coverage from GSC queries, sales calls, support tickets, and competitor gaps.
Knowledge Base search returns irrelevant results	The wrong Knowledge Base is selected, or auto-selection is searching too broadly.	Select the Knowledge Base by name in the step's Knowledge Base picker.
A downstream Section cannot find an Artifact	The Section is referencing the Artifact by filename.	Reference the Artifact by name. Use the slash menu to insert the reference.
Triggered run uses old Playbook content	The Trigger is pinned to an older published version.	Open the Trigger and select Default or the published version you want to run.
Triggered run fails after changing Inputs	The active Playbook version has required Inputs that are not configured on the Trigger.	Open the Trigger settings and update the Input configuration.
Grid run fails after changing Inputs	The Grid column is using a Playbook version with required Inputs that are not mapped.	Open the Grid column settings and update the Input mappings.
Session-chat edits do not update the Playbook	The Session is running a published version. Chat edits apply to Artifacts only.	Open the Playbook in the editor and edit the Playbook with Quill, or make direct edits.
Replicated Playbook is missing Tools	The Workflow converter did not carry every Tool reference into the Playbook.	Add missing Tools with the slash menu before publishing.
Playbook stalls on Section 1 asking which row to run	The run is using the internal __id column as the row identifier from a Grid.	Pass a real identifier column, such as URL or slug, to the Playbook instead of __id.
A Playbook is not available in a Grid	The Playbook is still a draft.	Publish the Playbook, then add it from the Grid's Playbooks tab.
AEO Insight is not available as a Trigger	AEO Insight triggers are not enabled for the workspace.	Use Schedule, Webhook, or Monitor, or contact your account team about AEO Insight triggers.
Webflow export overwrote custom content	The native export pushes the full rich-text field.	Plan the field structure so the Playbook output owns the field it exports to.
Slack messages do not tag individuals	Individual @mentions are not supported in Playbook Slack steps yet.	Name the person in the message body and have reviewers watch the relevant channel.

Frequently asked questions

Can I keep existing Workflows running while I build Playbooks?

Yes. Playbooks and Workflows can run in parallel during migration.

Do Playbooks support BYOK?

Playbooks do not currently support BYOK. Contact [e-mail] if you have questions about model access in Playbooks.

Can I route reviews to different people based on content type or complexity?

Not natively yet. The current workaround is to create separate Sections with skip logic, such as "If complexity is not 3, skip this Section." Each Section can have its own reviewer assignment.

Can Playbooks push content directly to my CMS?

Yes, but keep publishing separate from content creation when possible. Create and review the content first, then publish from a Grid column, a separate publishing Playbook, or a CMS MCP. If a Playbook or CMS MCP publishes or refreshes a page, call the AirOps MCP track_aeo_page_content_update tool with the page URL and update type so AirOps Insights can track the content update.

What SEO tools are available in Playbooks?

Playbooks can use AirOps SEO Research, DataForSEO, Moz, Google Search Console, Page 360 Report, and Page Versus Report. They can also use web research tools like Google Search, Parallel Web Systems, Firecrawl, Reddit, and Web Page Scrape.

How do I trigger a Playbook programmatically?

Use a Webhook Trigger. Webhooks are the recommended way to start a published Playbook from an external system. Send a POST request to the webhook URL with an inputs object that uses Playbook Input variable names as keys. See Playbook Triggers for the payload format. The Trigger runs its selected version: Default follows the current published version, and a pinned Trigger keeps using the selected version until you change it. If the Playbook Inputs change, update the Trigger's Input configuration before sending production requests.

Can Quill edit a Playbook from a running Session?

No. Edits in a Session chat apply to the Artifacts. To modify the Playbook, open it in the editor and use Quill there.

Can a Playbook remember things across runs?

Yes. Memory persists information across Sessions. A common pattern is a Playbook that monitors data and avoids recommending the same content for refresh within a rolling window, such as 60 days.