> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildassistants.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues And Solutions

## Overview

There is a lot we try to keep out of your hands so you have to do as little work as possible. However, we don't have control over a couple of things that can affect your AI assistant's performance. Understanding these limitations helps you troubleshoot issues more effectively and optimize your setup.

## Platform Limitations

buildassistants.app handles most technical complexity automatically, but there are several areas where external factors or user configuration can impact performance. Here are the most common issues and their solutions.

## 1. GoHighLevel Calendars and Calendar Configurations

### The Issue

**What we control:** API integration and booking logic
**What we don't control:** Calendar settings and configurations within GoHighLevel

### How It Works

Your AI will pull true-to-time availability from your GoHighLevel calendar via API v2 (OAuth) using GoHighLevel's very own availability endpoint on scheduling pages. This means we get the most accurate times from GoHighLevel based on your current settings.

### Common Problems

#### Availability Discrepancies

**Problem:** AI shows different available times than expected
**Solution:** Check your calendar settings in your sub-account

#### Booking Conflicts

**Problem:** Double bookings or unavailable times being offered
**Solution:** Review calendar configurations and buffer times

#### Time Zone Issues

**Problem:** Appointments scheduled in wrong time zone
**Solution:** Verify time zone settings in GoHighLevel calendar

### Troubleshooting Steps

1. **Verify Calendar Settings:**
   * Check availability hours in GoHighLevel
   * Confirm buffer times between appointments
   * Review any booking restrictions or rules

2. **Test API Connection:**
   * Ensure OAuth connection is active
   * Verify calendar permissions are properly set
   * Test booking flow manually

3. **Check Integration:**
   * Confirm calendar is properly linked to AI assistant
   * Verify calendar unique identifier is correct
   * Test with simple booking requests

### Best Practices

* **Consistent Settings:** Maintain consistent calendar configurations across sub-accounts
* **Regular Audits:** Periodically review calendar settings for accuracy
* **Buffer Times:** Set appropriate buffer times to prevent scheduling conflicts
* **Time Zones:** Ensure all calendars use consistent time zone settings

## 2. GoHighLevel API v2 (OAuth) Initial Connection

### The Issue

**Critical Connection:** If done correctly, this only ever has to be done once over the life of your account
**User-Dependent:** Improper initial configuration can cause ongoing issues

### Why This Matters

We were early users to API v2 so we've mastered the logistics of the system. However, one thing we cannot control is what you click during the initial connection process.

### Common Connection Problems

#### Improper Initial Setup

**Problem:** OAuth connection configured incorrectly during setup
**Consequences:**

* Need to reset connection for new sub-accounts
* Loss of connection over time
* Inconsistent data synchronization

#### Permission Issues

**Problem:** Insufficient permissions granted during OAuth setup
**Symptoms:**

* Limited calendar access
* Unable to create or modify appointments
* Missing contact information

#### Account Scope Problems

**Problem:** OAuth connected to wrong account or limited scope
**Issues:**

* Sub-accounts not syncing properly
* Missing agency-level permissions
* Restricted API access

### Prevention and Solutions

#### During Initial Setup

1. **Follow Setup Guide Carefully:**
   * Use provided OAuth setup instructions exactly
   * Don't skip steps or make assumptions
   * Verify all permissions are granted

2. **Account Selection:**
   * Ensure you're connecting the correct GoHighLevel account
   * Verify agency-level access when needed
   * Confirm all required scopes are included

3. **Testing After Setup:**
   * Test calendar integration immediately
   * Verify sub-account syncing works properly
   * Confirm all expected features are functional

#### If Problems Occur

1. **Contact Support:** Before attempting to reset OAuth connection
2. **Document Issues:** Note specific symptoms and error messages
3. **Professional Reset:** Allow buildassistants.app team to guide OAuth reset process

## 3. Response Issues and LLM Error Handling

### Our Coverage

We have 99.9% of LLM and AI vendor error handling in place to ensure minimal downtime. However, AI and prompting involve many variables that are impossible to account for until encountered.

### Common LLM Issues

#### Tool Calling Problems

**Issue:** Improper tool calling configurations
**Symptoms:**

* Tools not triggering when expected
* Wrong tools being called
* Parameters not being passed correctly

**Solutions:**

* Review tool descriptions for clarity
* Verify parameter configurations
* Test tool calling with simple scenarios

#### Response Generation Errors

**Issue:** AI fails to generate appropriate responses
**Symptoms:**

* Generic or unhelpful responses
* Incomplete information delivery
* Unexpected response formats

**Solutions:**

* Check prompt clarity and specificity
* Verify knowledge base integration
* Review conversation context handling

#### API Timeout Issues

**Issue:** External API calls timing out
**Symptoms:**

* Delayed responses
* Failed tool executions
* Incomplete data retrieval

**Solutions:**

* Check external service status
* Verify API endpoint availability
* Review timeout configurations

### Error Handling Approach

#### Proactive Monitoring

* **Continuous Improvement:** As we encounter unique break-cases and bugs, we fix them
* **Pattern Recognition:** Common issues are documented and resolved systematically
* **Preventive Measures:** Known problems are prevented through improved error handling

#### User Reporting

* **Issue Documentation:** Report unusual behaviors with specific examples
* **Context Sharing:** Provide conversation context when reporting problems
* **Collaborative Solutions:** Work with support team to identify root causes

## 4. "Off the Rails" or Not Following Instructions

### The Reality

Unfortunately, we don't control the correlation of response-to-query percentages based on instructions. If your AI model goes "off the rails" or doesn't properly follow instructions, this can usually be linked back to prompting.

### Understanding the Challenge

**AI Limitations:** No AI system has perfect instruction following
**Prompting Impact:** How you instruct your AI significantly affects performance
**Variable Factors:** Context, complexity, and specificity all influence outcomes

### Common "Off the Rails" Scenarios

#### Topic Drift

**Problem:** AI strays from intended conversation topic
**Causes:**

* Unclear conversation boundaries in prompts
* Insufficient topic guidance
* Complex or ambiguous user queries

**Solutions:**

* Add clear topic boundaries to prompts
* Include instructions to redirect conversations
* Provide specific examples of desired behavior

#### Instruction Deviation

**Problem:** AI doesn't follow specific procedural instructions
**Causes:**

* Conflicting instructions in prompts
* Overly complex instruction sets
* Ambiguous or unclear directives

**Solutions:**

* Simplify and clarify instructions
* Remove conflicting directives
* Test instructions with various scenarios

#### Inappropriate Responses

**Problem:** AI provides responses that don't match brand or context
**Causes:**

* Insufficient context in prompts
* Missing brand guidelines
* Inadequate response examples

**Solutions:**

* Include clear brand voice guidelines
* Provide specific response examples
* Set appropriate conversation boundaries

### Best Practices for Prompt Engineering

#### Prompt Creation

**Generated Prompts:** We generate torture-tested prompts for you during assistant creation
**Deviation Warning:** With deviation from these instructions, we cannot control how well your AI performs

#### Optimization Guidelines

1. **Start with Provided Prompts:**
   * Use our generated prompts as the foundation
   * Make minimal, targeted modifications
   * Test changes thoroughly before deploying

2. **Clear Instructions:**
   * Be specific about desired behaviors
   * Include examples of good and bad responses
   * Set clear boundaries for conversation topics

3. **Iterative Improvement:**
   * Make small changes and test results
   * Document what works and what doesn't
   * Build on successful configurations

4. **Context Awareness:**
   * Include relevant business context
   * Specify target audience characteristics
   * Provide industry-specific guidance

### Troubleshooting Steps

#### When AI Goes Off-Topic

1. **Review Recent Changes:** Check for recent prompt modifications
2. **Analyze Conversation Context:** Look for patterns in problematic responses
3. **Test with Simple Scenarios:** Verify basic functionality still works
4. **Revert if Necessary:** Return to previously working configuration

#### For Persistent Issues

1. **Document Specific Examples:** Provide exact user inputs and AI responses
2. **Contact Support:** Share problematic conversations with support team
3. **Collaborative Analysis:** Work with team to identify root causes
4. **Implement Solutions:** Apply recommended fixes systematically

## Prevention Strategies

### Regular Maintenance

* **Monitor Performance:** Regularly review AI conversation quality
* **Update Configurations:** Keep calendar and API settings current
* **Test Functionality:** Periodically test all integrated features
* **Review Prompts:** Assess prompt effectiveness over time

### Quality Assurance

* **User Feedback:** Collect and analyze user interaction feedback
* **Performance Metrics:** Monitor response accuracy and user satisfaction
* **Continuous Improvement:** Apply lessons learned to prevent future issues
* **Documentation:** Maintain records of successful configurations

### Support Resources

* **Knowledge Base:** Utilize platform documentation and guides
* **Community Support:** Engage with other users for best practices
* **Professional Support:** Contact buildassistants.app team for complex issues
* **Training Resources:** Stay updated with platform improvements and features

## When to Contact Support

### Immediate Support Needed

* **OAuth Connection Issues:** Before attempting to reset connections
* **Persistent AI Problems:** When AI consistently fails to perform
* **API Integration Failures:** When external integrations stop working
* **Data Loss or Corruption:** When important configurations are lost

### Information to Provide

* **Specific Examples:** Exact user inputs and AI responses
* **Error Messages:** Any system error messages or codes
* **Configuration Details:** Current prompt and tool configurations
* **Timeline:** When issues started and any recent changes made

Understanding these common issues and their limitations helps you work more effectively with buildassistants.app while knowing when to seek support for complex problems.