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 your Git provider
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 — 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 on the milestone card — Often resolves the issue
2. Check permissions — needs permission to create branches and PRs in your Git provider
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 — 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 in your Git provider
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

​

Pool Busy — All Workers Busy

What happened: You tried to start a milestone, ad-hoc execution, or similar work and saw “All workers in this project’s pool are busy — try again when one frees up.” Why this happens: Every daemon in the project’s pool is already running an execution. Non-chat work is blocked until a worker becomes available. Resolution:

1. Wait — a running execution will finish and free a worker
2. Check pool activity — look at the project sidebar or Build Environment page to see what is running on each daemon
3. Add capacity — register additional daemons into the pool to handle more concurrent work

​

Another User Is Using Knowledge Chat

What happened: You tried to open a Knowledge chat or Code 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

​

Waiting for Exclusive Access / Move to a Free Worker

What happened: Your chat session is parked because another job on the same daemon needs exclusive access to the application (for example, running lifecycle commands). Why this happens: Some operations require exclusive control of the application process on the worker. If the daemon is already running such an operation, the chat waits until it finishes. Resolution:

1. Wait — the operation will finish and your chat resumes automatically
2. Move to a free worker — if the pool has another available daemon, offers a Move to a free worker option so your chat can continue on a different daemon without waiting

​

Project Not Connected to a Pool

What happened: You tried to run work on a self-hosted project but there is no daemon pool connected. Resolution:

1. Go to Build Environment in the project settings
2. Join an existing pool or create a new one and register a daemon into it
3. Once a pool is connected with at least one online daemon, you can start work

​

No Live Daemons in Pool

What happened: The project is connected to a pool, but all daemons in the pool are offline. Resolution:

1. Check that at least one daemon host is running mcode — run mcode logs on the host to see recent errors
2. Verify network connectivity from the host to over HTTPS
3. See Self-hosted Daemon — Troubleshooting for detailed steps

​

Pull Request Issues

​

PR Not Detected as Merged

What happened: You merged the PR 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 your Git provider — 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 as you normally would in your Git provider
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 repositories don’t appear in the selection list. Try these:

1. Check your Git provider 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 app installation

​

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 app installation — Ensure the repositories are included in your Git provider’s 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