Skip to content

Troubleshooting for Practitioners

Encountering an issue while running a workflow? Most common problems can be resolved by checking your configuration or providing more context to the agent.

1. Command Issues

"Command not found"

If you type a command like /content-audit and receive an error that it doesn't exist: 1. Check Discovery: Run /utils:commands to see the current list of active commands. 2. Verify Installation: Ensure the relevant plugin (e.g., the SEO plugin) is correctly linked or installed. Refer to the Quickstart Guide. 3. Core Dependencies: Ensure the core-dependencies plugin is installed, as all other plugins require it to function.

2. Data & MCP Connection Issues

The agents rely on Model Context Protocol (MCP) servers to pull data from external sources like BigQuery and DataForSEO.

MCP Connection Errors

If you see errors related to "BigQuery," "DataForSEO," or "Wrike": * Authentication: Check your .env file to ensure all API keys and Project IDs are correct. * Timeouts: Large data requests may occasionally time out. Try narrowing your request (e.g., audit one URL instead of a whole subdirectory). * Missing Variables: Ensure you have restarted your OpenCode session after adding new environment variables.

"No data found for this client"

If the agent reports it can't find data: * Verify Credentials: Double-check that your BigQuery project has access to the specific client data you're requesting. * Manual Fallback: Most workflows allow you to provide data manually if the automated connection fails. The agent will prompt you for this if it hits a roadblock.

3. Response & Quality Issues

Slow Responses

Complex workflows like /search-landscape involve heavy data processing. * Expectation: These workflows can take 10–15 minutes to gather and analyze data. * API Latency: Sometimes external APIs (like DataForSEO) respond slowly. The agent will usually notify you if it's waiting on a external source.

Generic or Low-Confidence Output

If the draft deliverable feels too generic: * Provide More Context: Re-run the command and be more specific during the Intake phase. Mention specific competitors, unique client challenges, or target audience nuances. * Check the Data Plan: Review the AI's data plan step to ensure it's looking at the right sources.

4. Getting Help

If you've tried the steps above and are still stuck:

  1. Check the Docs: Review the Getting Started guide.
  2. File an Issue: Create a GitHub issue in the agents-infra repository. Please include:
    • The command you were running.
    • The exact prompt you used.
    • The error output or a description of what went wrong.
    • Which MCP servers you have configured.