> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues

export const ProductName = "The Morph Platform";

export const productName = "the Morph Platform";

This guide covers common issues and how to resolve them.

## Generation Failures

### Codebase Analysis Failed

**What happened:** {productName} couldn't analyze your repositories.

**Try these:**

1. **Check repository access** — Ensure {productName} 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:** {productName} 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:** {productName} 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](/setup/build-environment/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** — {productName} 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](/customization/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** — {productName} 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 {productName} still shows "Pending Review."

**Try these:**

1. **Refresh {productName} 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](mailto: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