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

# Troubleshooting

> Diagnose and resolve common Blitzy platform issues across project setup, code generation, environments, and reviews

Resolve common platform issues. For integration-specific problems (GitHub, GitLab, Azure DevOps), see [Integration Troubleshooting](/integrations/troubleshooting).

<Note>
  **Jump to:** [Project Setup](#project-setup) | [Code Generation](#code-generation) | [Environments](#environments) | [Reviews](#reviews-and-pull-requests) | [Getting Help](#getting-help)
</Note>

## Project Setup

<AccordionGroup>
  <Accordion title="Repository not appearing after connecting integration">
    <Steps>
      <Step title="Verify integration status">
        Confirm the integration shows **Connected** in **Settings > Integrations**
      </Step>

      <Step title="Check repository access">
        Confirm the Blitzy app has access to the specific repository (not just the organization)
      </Step>

      <Step title="Verify provider-specific settings">
        * **GitHub** - Go to **GitHub Settings > Applications > Blitzy** and confirm repository access
        * **GitLab** - Ensure the OAuth token has `api` and `read_api` scopes
        * **Azure DevOps** - Confirm project-level access in your service connection settings
      </Step>
    </Steps>

    If the repository still doesn't appear, disconnect and reconnect the integration.
  </Accordion>

  <Accordion title="Ingestion fails or produces incomplete Technical Specification">
    Common causes:

    * **Repository too large** - Narrow scope with a `.blitzyignore` file to exclude vendor directories, generated code, or test fixtures
    * **Missing branch access** - Ensure Blitzy has read access to the target branch
    * **Ingestion prompt too vague** - Provide specific architecture details (patterns, layers, domain terminology) in your [ingestion prompt](/prompt-engineering/ingestion)

    If ingestion completes but the Tech Spec is missing sections, refine the spec directly in the [Knowledge Base](/platform/knowledge-base).
  </Accordion>

  <Accordion title="Cannot create a project for a monorepo or multi-repo setup">
    * **Monorepos** - Configure submodule paths in [project settings](/administration/submodules) to scope Blitzy to specific directories
    * **Multi-repo** - Each repository needs its own project. Connect each repo separately through [Sharing](/project-lifecycle/sharing)
    * Review the [Codebase Setup guide](/codebase-setup) for detailed repository structure guidance
  </Accordion>
</AccordionGroup>

## Code Generation

<AccordionGroup>
  <Accordion title="Generation takes longer than expected">
    Generation time varies by scope. Typical ranges:

    * **Small feature** (1-10 files) - minutes
    * **Medium feature** (10-50 files) - tens of minutes
    * **Large feature or new product** (50+ files) - may take longer

    If generation appears stuck, check the Workspace for status updates. Do not cancel and restart; this loses progress.
  </Accordion>

  <Accordion title="Pushed changes to the blitzy branch during generation">
    Do not push commits to the `blitzy` branch while code generation is in progress. Pushing during generation causes merge conflicts, lost progress, or broken builds.

    If this has already happened:

    <Steps>
      <Step title="Wait for generation">
        Wait for the current generation to complete (or fail)
      </Step>

      <Step title="Close the pull request">
        Close the resulting pull request
      </Step>

      <Step title="Reset the branch">
        Reset the `blitzy` branch to a clean state from your base branch
      </Step>

      <Step title="Re-run generation">
        Re-run ingestion and generation with a fresh prompt
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Generated code doesn't match existing patterns">
    This usually indicates the Technical Specification needs refinement:

    <Steps>
      <Step title="Review the spec">
        Toggle to [Knowledge Base](/platform/knowledge-base) and review the spec for accuracy
      </Step>

      <Step title="Check documented patterns">
        Confirm your architecture patterns, naming conventions, and directory structure are documented in the spec
      </Step>

      <Step title="Refine the ingestion prompt">
        Use an [ingestion prompt refinement](/prompt-engineering/ingestion) to add missing context
      </Step>

      <Step title="Fix the current generation">
        Use [Refine](/pull-request-review/refine) with specific pattern directives
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Generated code fails to build or has runtime errors">
    * **Check environment configuration** - Ensure build instructions, dependencies, and environment variables are correctly set in [Environments](/administration/environments)
    * **Review the Project Guide** - It documents what was built and any known limitations
    * **Check for missing secrets** - If your build requires API keys or database connections, ensure they are configured as [environment secrets](/administration/environments)
    * If the issue is a specific code defect, use [Refine](/pull-request-review/refine) with the exact error message
  </Accordion>

  <Accordion title="Agent Action Plan is too broad or misses requirements">
    The AAP reflects how Blitzy interpreted your prompt. To improve it:

    * **Edit inline** - Modify specific plan items directly in the AAP review UI
    * **Refine the prompt** - Add explicit scope boundaries, file-level specificity, or constraints
    * **Add Rules** - Attach [Rules](/prompt-engineering/rules) to enforce patterns (e.g., test coverage, backward compatibility)
    * Review the [AAP Review guide](/project-lifecycle/aap-review) for the full refinement workflow
  </Accordion>

  <Accordion title="Spreadsheet data not reflected in generation despite being in the repository">
    Blitzy reads CSV, Excel, ODS, and Parquet files from your repository during ingestion and code generation. If your spreadsheet data is not reflected:

    * Verify the file is committed to the branch Blitzy is analyzing (not just local)
    * Check that the file is not excluded by `.blitzyignore`
    * Re-run ingestion to pick up newly added files

    **Note:** Spreadsheet files are **not supported as prompt attachments**. To include tabular data in a prompt, convert it to **Markdown** or **PDF** before attaching. See [Supported File Formats](/prompt-engineering/ingestion#supported-file-formats) for details.
  </Accordion>

  <Accordion title="Pull request was not created after generation completed">
    * Verify the target branch exists and Blitzy has write access
    * Check that no branch protection rules are blocking PR creation
    * For GitHub Enterprise: ensure the Blitzy app has the `pull_requests: write` permission
    * If the generation completed with errors, review the generation log in Workspace for details
  </Accordion>
</AccordionGroup>

## Environments

<AccordionGroup>
  <Accordion title="Build fails during runtime validation">
    Runtime validation runs your build commands in an isolated environment. Common failures:

    * **Missing dependencies** - Ensure all package managers and build tools are specified in your environment setup
    * **Missing environment variables** - Add required variables in [Environment Configuration](/administration/environments)
    * **Database or service dependencies** - Configure connection strings and ensure external services are accessible
    * **Incorrect build commands** - Verify your build/test commands work locally before configuring them in Blitzy
  </Accordion>

  <Accordion title="Secrets not available during generation">
    * Secrets are encrypted at rest and masked in logs. They do not appear in plain text in any output
    * Verify the secret was saved (not just the variable name) in **Settings > Environments**
    * Secrets are scoped to the environment. Ensure you are targeting the correct environment
    * Secrets are **not** sent to AI agents; they are only used during runtime validation
  </Accordion>
</AccordionGroup>

## Reviews and Pull Requests

<AccordionGroup>
  <Accordion title="Project Guide is missing or incomplete">
    Project Guides are generated automatically with every code generation. If it is missing:

    * Check the PR description for the Project Guide link
    * For follow-up generations, the Project Guide updates incrementally
    * Review the [Project Guide Review guide](/project-lifecycle/project-guide-review) for what to expect
  </Accordion>

  <Accordion title="Refine request didn't address the issue">
    Effective refine requests are specific and scoped:

    * **Do:** "Change the `UserService.create()` method to validate email format before saving"
    * **Don't:** "Fix the code" or "Make it better"
    * Include the exact file paths, function names, and expected behavior
    * See the [Refine guide](/pull-request-review/refine) for directive format and best practices
  </Accordion>

  <Accordion title="Should I refine or close and start over?">
    | Situation                              | Action                                                         |
    | :------------------------------------- | :------------------------------------------------------------- |
    | Specific code issues, correct approach | [Refine](/pull-request-review/refine)                          |
    | Wrong architecture or approach         | [Close](/pull-request-review/close) and improve prompt         |
    | Missing major features                 | [Close](/pull-request-review/close) and expand prompt scope    |
    | Minor gaps or edge cases               | [Refine](/pull-request-review/refine) with targeted directives |
  </Accordion>
</AccordionGroup>

## Getting Help

If your issue is not covered above:

<Steps>
  <Step title="Check integration docs">
    Review the [Integration Troubleshooting](/integrations/troubleshooting) page for SCM-specific issues
  </Step>

  <Step title="Review common questions">
    Check [Common Questions](/platform/workspace#common-questions) in the Workspace guide for workflow questions
  </Step>

  <Step title="Contact support">
    Email **[support@blitzy.com](mailto:support@blitzy.com)** with:

    * Description of the issue and steps to reproduce
    * Screenshot or error message
    * Project name and repository
    * What you expected vs. what happened
  </Step>
</Steps>