Troubleshooting

This guide covers common issues and how to resolve them.

​

Generation Failures

​

Codebase Analysis Failed

What happened: couldn’t analyze your repositories. Try these:

1. Check repository access — Ensure has permission to read your repositories
2. Verify the repositories are accessible — Try accessing them directly in GitHub
3. Click Try Again — Transient errors often resolve on retry
4. Check repository size — Very large repositories may need more time

If failures persist, contact support with your project name.

​

Project Spec generation failed

What happened: couldn’t generate the Project Spec from your goal. Try these:

1. Make your goal more specific — Vague goals are harder to process
2. Check your modernization goal — Does it describe a clear transformation?
3. Click Try Again — Retry often resolves transient issues

​

Roadmap Generation Failed

What happened: couldn’t plan the milestone sequence or generate the roadmap. Try these:

1. Review your Project Spec — Are there conflicting requirements?
2. Check for complex requirements — Unusual combinations may cause issues
3. Click Try Again — Transient errors may resolve

​

Build Environment Issues

​

Validation Failed

What happened: The end-to-end validation of your build environment didn’t pass. Try these:

1. Check lifecycle commands — Verify that install, build, run, and test commands work when run manually
2. Check environment variables — Missing or incorrect variables are a common cause
3. Review the validation logs — They show which step failed and the error output
4. For Self-hosted Daemon — Ensure the daemon is online and has access to required services (private registries, databases, APIs)

​

Health Check Timed Out

What happened: The application started but the health check never succeeded. Try these:

1. Confirm the health check URL and port — They must match your application’s configuration
2. Check that the application binds to the correct interface — Use 0.0.0.0 or localhost
3. Increase the timeout — If your application has a long startup sequence

​

Daemon Shows as Offline

What happened: The Self-hosted Daemon is not responding. Try these:

1. Check if the process is running — Run ps aux | grep mcode on the host machine
2. Check network connectivity — The daemon must reach Morph over HTTPS
3. Check the daemon logs — Run mcode logs for recent errors
4. Restart the daemon — Run mcode run or mcode start

See Self-hosted Daemon for full setup and troubleshooting details.

​

Milestone Issues

​

Task Execution Failed

What happened: One or more tasks failed during milestone execution. Try these:

1. Expand the milestone — See which task failed and the error message
2. Click Retry Execute — Many failures are transient
3. Review the milestone description — Unclear instructions can cause failures
4. Check lifecycle commands — Incorrect install/build/test commands configured in the build environment can fail execution

For persistent failures, contact support with the error message.

​

PR Generation Failed

What happened: Tasks completed but the Pull Request couldn’t be created. Try these:

1. Click Retry PR — Often resolves the issue
2. Check GitHub permissions — needs permission to create branches and PRs
3. Check branch protection rules — Some rules may block automated PRs
4. Verify repository access — Ensure permissions haven’t changed

​

PR Checks Failed

What happened: The Pull Request was created but CI/CD checks failed. This is normal. The generated code may need adjustments for your specific CI pipeline. Try these:

1. Review the failing checks in GitHub — Understand what failed
2. Common causes:
   • Linting violations (style doesn’t match your config)
   • Test failures (some tests may need updates)
   • Build errors (configuration differences)
3. Make manual fixes — Push additional commits to the PR
4. Merge when checks pass

For recurring issues, consider creating Rules to prevent them.

​

Milestone Stuck in “In Progress”

What happened: The milestone shows as running but nothing is happening. Try these:

1. Refresh the page — Status updates may not have rendered
2. Wait a few minutes — Some operations take time
3. Check for errors — Expand the milestone to see if a task failed
4. Contact support — If truly stuck for more than 30 minutes

​

Can’t Start Next Milestone

What happened: The next milestone won’t unlock. Why this happens: Milestones are sequential. Each must complete before the next begins. Check:

1. Is the previous milestone merged? — Just having the PR isn’t enough; you must merge it
2. Did the previous milestone’s PR merge successfully? — Check GitHub
3. Refresh the page — polls for merge status periodically

​

Pull Request Issues

​

PR Not Detected as Merged

What happened: You merged the PR in GitHub but still shows “Pending Review.” Try these:

1. Refresh page — Status updates poll periodically
2. Wait 1-2 minutes — There’s a short delay between merge and detection
3. Verify in GitHub — Confirm the PR is actually merged (not just approved)
4. Contact support — If not resolved after several minutes

​

Merge Conflicts

What happened: The PR has conflicts with the target branch. Why this happens:

• Manual changes were made to the repository between milestones
• Another branch was merged that conflicts

Resolution:

1. Resolve conflicts in GitHub as you normally would
2. Push the resolution
3. Merge the PR

​

Can’t Open PR

What happened: Clicking “Review Pull Request” doesn’t open anything. Try these:

1. Check your popup blocker — The PR opens in a new tab
2. Check the milestone status — Is a PR actually ready?
3. Refresh and try again

​

Access Issues

​

Can’t See My Repositories

What happened: Your GitHub repositories don’t appear in the selection list. Try these:

1. Check GitHub connection — You may need to reconnect
2. Check repository permissions — Did you grant access to the specific repo?
3. For organization repos — You may need admin approval for the GitHub App

​

Can’t Create Project

What happened: Repository selection or project creation fails. Try these:

1. Check permissions — Ensure you have access to the repositories
2. Try a different repository — To isolate the issue
3. Verify GitHub App installation — Ensure the repositories are included in your GitHub App configuration

​

Getting Help

​

Contact Support

For issues not covered here:

1. Email support@modelcode.ai
2. Include:
   • Your project name
   • What you were trying to do
   • The error message (if any)
   • Screenshots (if helpful)

​

Response Times

• Business hours: 2-4 hours
• After hours: Next business day