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 respect a dependency graph. A milestone stays locked until all milestones it depends on are merged. Check:

1. Are all prerequisite milestones merged? — Look at which milestones yours depends on
2. Did the prerequisite’s PR merge successfully? — Check GitHub
3. Refresh the page — polls for merge status periodically

​

Milestone Shows “Rebase Required”

What happened: A sibling milestone was merged and this milestone’s branch now needs to incorporate those changes. Why this happens: When multiple milestones run in parallel and one merges into the feature branch, remaining in-progress branches may diverge. Resolution:

1. Click the Rebase action on the milestone card
2. The agent incorporates the upstream changes automatically
3. Once complete, review and merge the updated PR as normal

​

Daemon Busy

What happened: Your action is queued because the daemon is already running a job. Why this happens: Each user’s daemon runs one job at a time (milestone execution, code review chat, knowledge chat). Resolution:

1. Wait — the current job will finish and yours will start automatically
2. Check what’s running — look at your active milestones or chat sessions to see which is using the daemon
3. If nothing appears active, the daemon may be finishing cleanup — wait a minute and retry

​

Another User Is Using Knowledge Chat

What happened: You tried to open a knowledge chat or review chat session but another user currently has an active session. Why this happens: Chat sessions are locked to one active user at a time to prevent conflicting instructions to the agent. Resolution:

1. Wait — the session unlocks when the other user finishes or their session times out
2. Coordinate — reach out to the team member shown in the lock message

​

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