Troubleshooting and Support

This section provides guidance on identifying and resolving common issues you might encounter while using or developing with AI Docs. Understanding these troubleshooting steps will help you quickly diagnose problems and get your documentation projects back on track.

General Troubleshooting Flow

Here's a general approach to troubleshooting issues with AI Docs:

Common Error Messages and Solutions

AI Docs provides specific error messages to help you understand what went wrong. Here's how to interpret and resolve them.

Page Not Found (404)

You might encounter a "Page Not Found" error in two main scenarios:

• Global Application 404: If you navigate to a non-existent URL on the main AI Docs application (e.g., aidocs.com/non-existent-path), you will see a comprehensive 404 page with quick links to other parts of the application. This indicates that the main application itself could not find the requested route.

• Project Documentation 404: If you access a non-existent documentation page within a specific project's generated documentation (e.g., your-project.aidocs.com/non-existent-doc), you will see a simpler "Page Not Found" message specific to the documentation site. This means the requested documentation page does not exist for that project.

Solution:

1. Check the URL: Ensure the URL is correctly typed.
2. Verify Project Status: If it's a project documentation page, confirm the project exists and the documentation has been successfully generated. You can check the project's status in the Monitoring Project Activity section.
3. Return Home: Use the provided "Return Home" or "Go to Home" buttons to navigate back to a known working page.

Page Error (Generic Documentation Page Error)

When a specific documentation page within a generated documentation site fails to load due to an unexpected issue, you might see a "Page Error" message. This indicates a problem during the rendering or data fetching for that particular page. The error message will typically state "This documentation page couldn't be loaded." or provide a more specific error if available.

Solution:

1. Try Again: Click the "Try Again" button to re-attempt loading the page. This can resolve transient network issues or temporary backend problems.
2. Go to Home: If retrying doesn't work, navigate back to the main application dashboard or the project's overview page using the "Go to Home" button.
3. Check Project Status: Review the project's status in Monitoring Project Activity for any ongoing generation issues.

Dashboard Error

If an error occurs while loading your main user dashboard, you will see a "Something went wrong" message. This typically indicates a problem fetching your projects or user data, preventing the dashboard from displaying correctly.

Solution:

1. Try Again: Click the "Try Again" button. This often resolves temporary issues with data retrieval.
2. Reload: Use the "Reload" button to perform a full page refresh, which can clear cached data and re-initialize the dashboard.
3. Check Network Connection: Ensure your internet connection is stable.
4. Contact Support: If the issue persists, it might indicate a deeper problem. Refer to the Getting Support section.

Documentation Rendering Error (MDX Syntax Issues)

This is a specific error that occurs when the generated documentation contains invalid MDX syntax, preventing it from being rendered correctly. This error is typically displayed within a project's detail view in the dashboard.

Solution:

1. Navigate to Project Overview: Go to the specific project's overview tab within your dashboard.
2. Regenerate Documentation: Click the "Regenerate Documentation" button. This action will delete all existing documentation for the project and trigger a new AI-powered generation process, which should correct any MDX syntax errors.

Troubleshooting Guides

This section covers common issues related to configuration, database, AI generation, and GitHub integration.

Environment Variable Configuration Issues

Incorrect or missing environment variables are a frequent cause of application failures.

Symptoms:

• Application fails to start.
• Authentication errors (e.g., Google OAuth not working).
• AI generation failures (e.g., OpenAI API key invalid).
• Database connection errors.
• GitHub integration issues.

Troubleshooting Steps:

1. Verify .env File: Ensure you have copied .env.example to .env and populated all required variables. Refer to Environment Configuration and Installation and Prerequisites.
2. Check Variable Values: Double-check that all API keys, client IDs, client secrets, and database connection strings are correct and do not contain typos.
3. Secrets: Ensure BETTER_AUTH_SECRET is a long, random string.
4. URLs: Confirm BETTER_AUTH_URL and NEXT_PUBLIC_APP_URL are set correctly for your environment (e.g., http://localhost:3000 for local development).
5. Restart Application: After any changes to .env, always restart your application (pnpm dev) to ensure the new variables are loaded.

Database Connection Problems

Issues connecting to or interacting with the PostgreSQL database can prevent AI Docs from storing and retrieving project or documentation data.

Symptoms:

• Application fails to start with database errors.
• Projects cannot be created, updated, or deleted.
• Documentation fails to generate or load.
• Errors related to Drizzle ORM.

Troubleshooting Steps:

1. DATABASE_URL: Verify that your DATABASE_URL in the .env file is correct and points to a running PostgreSQL instance. Refer to Environment Configuration and Installation and Prerequisites.
2. PostgreSQL Status: Ensure your PostgreSQL database server is running and accessible from your application's environment.
3. Firewall/Network: Check if any firewalls or network configurations are blocking the connection to your database.
4. Schema Migration: If you've updated the codebase or are setting up for the first time, ensure your database schema is up-to-date by running:
   bash

   pnpm db:generate
   pnpm db:push
   

   These commands generate and apply any necessary database schema changes.
5. Database Logs: Check your PostgreSQL database logs for more specific error messages.

AI Generation Failures

Problems during the AI-powered documentation generation process can lead to incomplete or missing documentation.

Symptoms:

• Documentation generation pipeline gets stuck or fails.
• Generated documentation is empty or contains placeholder text.
• Errors related to OpenAI or LangChain in logs.

Troubleshooting Steps:

1. OPENAI_API_KEY: Ensure your OPENAI_API_KEY in the .env file is valid and has sufficient credits. Refer to Environment Configuration and AI-Powered Generation.
2. Rate Limits: Check if you are hitting OpenAI API rate limits. Intense usage or misconfiguration can lead to issues.
3. Inngest Dashboard: AI Docs uses Inngest for background jobs like documentation generation. Check the Inngest dashboard for your project to see the status of project.ingest or project.generateDocsTree events. Failed jobs often provide detailed error messages.
4. Regenerate Documentation: As a primary solution, use the "Regenerate Documentation" button on your project's dashboard. This re-triggers the entire generation pipeline.
5. Model Availability: Occasionally, specific OpenAI models might experience temporary outages. Check OpenAI's status page.

GitHub Integration Problems

Issues with GitHub integration can prevent AI Docs from accessing repositories or receiving webhook updates.

Symptoms:

• Cannot connect AI Docs to a GitHub repository.
• Documentation does not update automatically after repository changes.
• Errors related to GitHub API calls.

Troubleshooting Steps:

1. GITHUB_TOKEN: Verify that your GITHUB_TOKEN in the .env file is valid and has the necessary repo scope. This token is used for general application-level GitHub interactions. Refer to GitHub Integration.
2. GitHub OAuth: If you're having trouble connecting your personal GitHub account for private repository access, ensure your GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correctly configured in .env and your GitHub OAuth App is set up correctly. Refer to Authentication and User Management.
3. Webhooks:
   • Go to your GitHub repository settings, then "Webhooks".
   • Ensure the AI Docs webhook is present and active.
   • Check the "Recent Deliveries" section for any failed deliveries and their error messages.
   • If the webhook is missing or misconfigured, deleting and re-creating the project in AI Docs will re-establish it. Refer to Webhooks for Automation.
4. Repository Permissions: Ensure the GitHub token or the connected user account has read access to the repository you are trying to document.

Performance and Loading Issues

While AI Docs includes loading indicators, prolonged loading times or unresponsive UI can indicate performance bottlenecks.

Symptoms:

• Dashboard or project pages load very slowly.
• UI feels sluggish or unresponsive.
• Documentation previews take a long time to render.

Troubleshooting Steps:

1. Network Speed: Ensure you have a stable and fast internet connection.
2. Browser Cache: Clear your browser's cache and cookies.
3. Server Resources: If self-hosting, check the resource utilization (CPU, RAM) of your server. High usage might indicate a need for more resources or optimization.
4. Database Performance: Slow database queries can impact overall application performance. Ensure your PostgreSQL instance is optimized and has sufficient resources.
5. AI Model Latency: AI generation can be time-consuming. If you're using larger or more complex AI models, expect longer generation times. Refer to AI-Powered Generation.
6. Rate Limiting: Excessive API calls to external services (like OpenAI or GitHub) can lead to delays if rate limits are hit.

Using Feedback for Improvement

AI Docs collects user feedback on documentation pages, which can be a valuable resource for identifying areas that need improvement. The Analytics and Feedback page provides a dashboard to view satisfaction rates, pages needing work, and user comments.

By monitoring this feedback, you can proactively address documentation gaps or unclear explanations, reducing the likelihood of users encountering issues that lead to support requests.

Getting Support

If you've followed the troubleshooting steps and are still experiencing issues, please gather as much information as possible and reach out for support.

Information to provide:

• A clear description of the problem.
• Any error messages you encountered (full text or screenshots).
• Steps to reproduce the issue.
• What troubleshooting steps you have already tried.
• Your environment details (e.g., local development, production deployment, Node.js version, pnpm version).

Providing detailed information will help the support team diagnose and resolve your issue more efficiently.