Jump to: Project Setup | Code Generation | Environments | Reviews | Getting Help
Project Setup
Repository not appearing after connecting integration
Repository not appearing after connecting integration
Check repository access
Confirm the Blitzy app has access to the specific repository (not just the organization)
Ingestion fails or produces incomplete Technical Specification
Ingestion fails or produces incomplete Technical Specification
Common causes:
- Repository too large - Narrow scope with a
.blitzyignorefile 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
Cannot create a project for a monorepo or multi-repo setup
Cannot create a project for a monorepo or multi-repo setup
- Monorepos - Configure submodule paths in project settings to scope Blitzy to specific directories
- Multi-repo - Each repository needs its own project. Connect each repo separately through Sharing
- Review the Codebase Setup guide for detailed repository structure guidance
Code Generation
Generation takes longer than expected
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
Pushed changes to the blitzy branch during generation
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:Generated code doesn't match existing patterns
Generated code doesn't match existing patterns
This usually indicates the Technical Specification needs refinement:
Review the spec
Toggle to Knowledge Base and review the spec for accuracy
Check documented patterns
Confirm your architecture patterns, naming conventions, and directory structure are documented in the spec
Refine the ingestion prompt
Use an ingestion prompt refinement to add missing context
Fix the current generation
Use Refine with specific pattern directives
Generated code fails to build or has runtime errors
Generated code fails to build or has runtime errors
- Check environment configuration - Ensure build instructions, dependencies, and environment variables are correctly set in 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
- If the issue is a specific code defect, use Refine with the exact error message
Agent Action Plan is too broad or misses requirements
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 to enforce patterns (e.g., test coverage, backward compatibility)
- Review the AAP Review guide for the full refinement workflow
Pull request was not created after generation completed
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: writepermission - If the generation completed with errors, review the generation log in Workspace for details
Environments
Build fails during runtime validation
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
- 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
Secrets not available during generation
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
Reviews and Pull Requests
Project Guide is missing or incomplete
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 for what to expect
Refine request didn't address the issue
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 for directive format and best practices
Getting Help
If your issue is not covered above:Check integration docs
Review the Integration Troubleshooting page for SCM-specific issues
Review common questions
Check Common Questions in the Workspace guide for workflow questions
Contact support
Email [email protected] with:
- Description of the issue and steps to reproduce
- Screenshot or error message
- Project name and repository
- What you expected vs. what happened