TroubleshootingCommon Issues
This guide helps you resolve the most common problems you might encounter while using Software Factory.
Problem: GitHub integration fails during setup.
Solutions:
Ensure you have admin access to the repository
Check that the repository is public or you have proper permissions
Verify the repository URL format (should be https://github.com/username/repo-name)
Try revoking and re-authorizing the GitHub App
Problem: Codebase indexing takes too long or gets stuck.
Solutions:
Large repositories may take 10-30 minutes to index
Check your internet connection
Ensure the repository is accessible
Contact support if indexing takes more than 30 minutes
Problem: Your coding agent (Cursor, Claude Code, etc.) can’t connect via MCP.
Solutions:
Verify your coding agent supports MCP
Double-check the connection string format
Regenerate the MCP connection string in Assembler
Ensure your agent has the necessary permissions
Problem: Work Orders don’t appear in Assembler.
Solutions:
Verify Work Orders are assigned to you in Planner
Check that Work Orders are in “Ready” or “In Progress” status
Refresh the Assembly Manager interface
Ensure you’re logged in with the correct account
Problem: PRD Editor is read-only or you can’t make changes.
Solutions:
Become the PRD “owner” first
Check if the PRD is versioned (old versions become read-only)
Create a new version of the PRD if needed
Contact the PRD owner to transfer ownership
Problem: UI mocks look broken or repetitive.
Solutions:
Use the Refresh button to randomize content while preserving layout
Try generating a new page with different parameters
Check that your browser supports the required features
Clear browser cache and try again
Problem: AI agent has trouble with large Blueprints or long sections.
Solutions:
Select only the relevant sections and restart the chat
Break large sections into smaller, focused parts
Use the Blueprint Navigator to work on specific sections
Consider splitting very large Blueprints into multiple documents
Problem: “Update from Codebase” doesn’t work for a section.
Solutions:
Manually trigger “Update from Codebase” via the section dropdown
Check that your repository is properly indexed
Verify the section is linked to the correct code files
Try refreshing the Blueprint and trying again
Problem: “Create with AI” doesn’t generate Work Orders.
Solutions:
Ensure your Blueprint is complete and Feature Nodes are up to date
Check that Blueprint sections have sufficient content
Try manually creating Work Orders and linking them to Blueprint sections
Refresh the Planner interface and try again
Problem: Can’t generate implementation plans for Work Orders.
Solutions:
Fill in the Work Order’s title and description first
Ensure the Work Order is connected to a Blueprint section
Check that your codebase is properly indexed
Try refreshing the Work Order editor
Problem: User feedback doesn’t show up in the Validator Inbox.
Solutions:
Verify your App Key and endpoint settings
Check that the API integration is properly configured
Ensure the feedback is being sent to the correct endpoint
Check for any rate limiting or authentication errors
Problem: Critical issues don’t trigger Slack alerts.
Solutions:
Check your SLACK_WEBHOOK_URL configuration
Verify the Slack webhook is active and accessible
Ensure notification rules are properly configured
Test the webhook with a simple message
Problem: Getting 403 errors when sending feedback.
Solutions:
Regenerate your App Key (starts with sf-int-)
Ensure the App Key is being sent in the correct format
Check that the App Key hasn’t expired
Verify the API endpoint URL is correct
Problem: Software Factory feels slow or unresponsive.
Solutions:
Check your internet connection
Try refreshing the page
Clear browser cache and cookies
Use a supported browser (Chrome, Firefox, Safari, Edge)
Contact support if problems persist
Problem: Can’t log in or stay logged in.
Solutions:
Clear browser cache and cookies
Try a different browser
Check that your account is active
Contact support if you can’t access your account
Problem: Changes don’t sync across modules or team members.
Solutions:
Refresh the page to sync latest changes
Check your internet connection
Ensure you’re working with the latest version
Contact support if sync issues persist
If you can’t resolve an issue using this guide:
Use In-Product Feedback - Click the feedback button in any module
Join Discord - Get help from the community: Discord Server
Contact Support - For urgent issues: sf-team@8090.ai
When reporting an issue, please include:
Description of the problem
Steps to reproduce
Screenshots if relevant
Browser and operating system information
Any error messages you see
Need more specific help? Check the full troubleshooting guide →
