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: has not heard from one of the machines in your project’s pool. Start in the app: open the Daemon pool section in your project’s Roadmap sidebar. It shows how many machines are online and which one is not, which tells you straight away whether this is one machine or the whole pool. If other machines are online, your work is not blocked — it will route to them. Then, on the affected machine, ask whoever administers it to check that the daemon is running, that outbound HTTPS is not blocked by a recent VPN or firewall change, and that its logs show no authentication errors. The most common cause is a host that rebooted without the daemon being installed as a service, so nothing brought it back up. See Daemon Administration for the full diagnostic steps.

​

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 Daemon Administration — When a daemon shows as offline for detailed steps

​

Daemon Install Refused on Windows (ARM or 32-bit)

What happened: install.ps1 stopped before installing anything. The ModelDaemon ships for Windows on amd64 only, and the installer checks the host’s architecture first:

• “Error: Windows on ARM is not supported. Use an x64 (amd64) Windows machine.”
• “Error: mcode has no 32-bit build. … A 64-bit version of Windows is required.”

Resolution:

1. Install the daemon on a 64-bit Windows amd64 host instead. Nothing was written on the refusing host, so there is nothing to clean up.
2. If your application has to build on Windows on ARM, contact support@modelcode.ai.

​

Daemon Registration Refused

What happened: The daemon installed, but registering it into the pool failed. A pool serves one platform, so a daemon is turned away at registration rather than joining and sitting idle. The message says which case you hit:

• “Daemon OS ’…’ does not match daemon pool ’…’” — the pool serves the other platform.
• “Daemon arch ’…’ does not match target pool arch ’…’” — the pool has an architecture pin and this host reports a different one.
• “…has live daemons on more than one OS (…). Remove the daemons that do not belong from the pool before adding a new one.” — the pool’s membership is inconsistent and has to be settled first.

Resolution:

1. Check the pool’s OS and Architecture on the pool details page, and compare them with the host you are installing on.
2. Install the daemon on a host matching the pool, and register it again. This is usually the quickest route.
3. For the third message, open the pool details page and Move or Remove the daemons whose platform doesn’t belong — both need the daemon to be idle — then register the new one.
4. If the host is the one you need and the pool is the wrong fit, create a new pool on that platform and register the daemon into it. A project already connected to the old pool stays there.

​

Execution Fails at Sandbox Creation on a Platform Mismatch

What happened: An execution failed while its sandbox was being created, because the daemon it was routed to runs a different operating system than the project. The project’s platform decides the shell its commands are written in, so the run stops rather than executing them on the wrong one. The project stays on the pool it was set up with, so the fix is to correct the pool’s membership. Resolution:

1. Open the pool details page — Manage in the ModelDaemon pool section of the project sidebar — and compare each daemon’s operating system with the project’s platform.
2. Move or Remove the daemon that doesn’t match, from the pool details page. Both actions need the daemon to be idle, so wait for its current job to finish.
3. Register a daemon running the project’s platform into the same pool, so there is somewhere for the work to go.
4. Retry the milestone from the roadmap.

If every daemon in the pool runs a different platform than the project, the pool isn’t the right home for it — contact support@modelcode.ai before deleting anything, since both the project’s platform and its pool are set at Build Environment setup.

​

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