Troubleshoot MergeLoom Ticket-to-Code Jobs

Most MergeLoom issues are easier to diagnose when you start in the right UI.

Use the customer controller for integrations, workflow rules, ticket intake, assignment, repository routing, Cloud Hosted runtime, billing, Controller Audit, and PR/MR coordination.

Use the Local Worker UI only for Self Hosted provider readiness, worker-local logs, live streams, Ticket Audit, Code Audit, runs, and health.

Quick Diagnostic Map

Symptom	Check first
Ticket did not start	Controller Audit, workflow intake settings, assignment, routing label.
Ticket was denied	Controller Audit and the work tracker comment.
Ticket routed to wrong repository	Repository Catalog alias and `repo-<alias>` label.
Cloud Hosted job stays pending	Cloud Runtime, email/card status, AI credits, run credits, provisioning readiness.
Self Hosted job stays pending	Worker enrollment, worker status, provider readiness, executor status.
Worker starts then fails	Local Worker UI Ticket Audit and live stream.
Validation fails	Repository validation commands, allowed commands, missing tools, timeout.
PR/MR not created	Code host permissions, branch push, publish-stage error, Retry Publish eligibility.
Audit looks empty	Correct execution mode, plan gates, cloud refresh timing, worker retention.

Ticket Does Not Match Intake

Check:

Scheduled intake is turned on in Workflow.
The intake source is correct.
The intake query, board, team, project, or WIQL is correct.
The work item has the managed label or tag, usually mergeloom.
The work item is in the configured ready state.
The work item is assigned to an active MergeLoom workspace user when assignment enforcement applies.
A repo-<alias> routing label is present when more than one work repository is enabled.

If a ticket is denied before a worker starts it, look in Controller Audit first. It may not appear in Self Hosted worker runs because no worker executed it.

Assignment Denial

MergeLoom can deny intake when the work item is:

unassigned
assigned to someone who is not an active MergeLoom workspace user
assigned in a format that does not match the workspace user’s provider identity

Fix the assignment in the work tracker or update Account & Access in the Controller UI. Then move the ticket back to the ready state or resync intake.

Repository Routing Fails

Use the Repository Catalog alias exactly:

repo-<alias>

Examples:

repo-api
repo-web
repo-worker

If only one enabled work repository exists, MergeLoom can default to it. If multiple enabled work repositories exist, use an unambiguous routing label or a work_repos directive.

Compatibility forms such as repo=api and repo:api may be accepted, but repo-api is the customer-facing label format.

Ticket Directives Fail

Directives must be inside a [JCA]...[/JCA] block in the ticket description.

Supported keys:

work_repos
context_repos
context_files
context_folders
inline_context
provider
model

Common failures:

unknown repository alias
disabled repository
invalid context file or folder path
provider not ready on an eligible worker
model not allowed by plan or provider policy

See Ticket Directives.

Continuation Comment Does Not Start

Use one of the accepted prefixes:

MergeLoom - please update the PR to also cover ...
MergeLoom: please update the PR to also cover ...
MergeLoom -> please update the PR to also cover ...

Then move the ticket back to the configured ready state.

Continuation expects a previous completed or blocked run with an actionable comment anchor. If the prefix is wrong or the previous run is not in the right state, Controller Audit can show that the item is waiting for continuation.

Retry Publish Is Not Available

Retry Publish appears only for eligible jobs:

the job is a failed standalone job
the publish gate is publish_failed
stored branch artifacts are available
the user is a workspace admin

Retry Publish does not rerun AI coding or validation. It reattempts PR/MR creation from stored artifacts and can consume a prepaid run credit.

MergeLoom does not use a general customer Rerun job button for normal recovery. Use a continuation comment for another code pass.

Cloud Hosted Will Not Start

Check the Controller UI:

Cloud Hosted is the selected execution mode.
Email verification is complete.
Payment/card verification is complete where required.
Cloud Runtime is ready.
AI credits are available.
Run credits are available.
The selected model is allowed by the plan.
The ticket has a valid route and eligible assignee.

Cloud Runtime and Cloud Audit can use recently refreshed views. If the state looks stale immediately after a run starts or ends, wait for the next refresh before assuming evidence is missing.

Self Hosted Worker Cannot Enroll

Check:

JCA_WORKER_CONTROL_PLANE_URL is https://controller.mergeloom.ai
JCA_WORKER_TENANT_SLUG matches the Controller UI worker setup page
JCA_WORKER_ENROLLMENT_TOKEN is current
the worker can reach the controller over the network
the workspace deployment mode is Self Hosted
Docker/Kubernetes logs show no repeated authorization failures

Docker logs:

docker compose logs -f
docker compose logs -f worker-gateway
docker compose logs -f worker-executor-1

Kubernetes logs:

kubectl get pods -n mergeloom
kubectl logs -n mergeloom -l component=gateway -f
kubectl logs -n mergeloom -l component=executor -f

Self Hosted Worker Is Idle

Check:

the worker status appears in the Controller UI
an executor is running, not only the gateway
provider readiness is green in /providers
the worker is allowed for the workspace deployment mode
plan concurrency is not exhausted
no stale active job is occupying the worker

MergeLoom can requeue stale active jobs after the stale timeout. If a job has been stuck longer than expected, check Controller Audit, Local Worker UI Runs, and support guidance before changing worker settings or retrying outside the UI.

Provider Is Not Ready

Check:

provider card readiness in the Local Worker UI
CLI login status inside the worker container, not just on the host
API key, bearer token, service account, IAM role, or workload identity
model or deployment name
base URL and region/project fields
network access from the worker container or pod
OpenAI-compatible tool-calling self-test result

Self Hosted provider parity varies by backend. Avoid assuming a private endpoint is compatible until the worker self-test passes.

Integration Cannot Connect

Check callback URLs:

https://controller.mergeloom.ai/api/integrations/jira/callback
https://controller.mergeloom.ai/api/integrations/confluence/callback
https://controller.mergeloom.ai/api/integrations/monday/callback
https://controller.mergeloom.ai/api/integrations/linear/callback
https://controller.mergeloom.ai/api/integrations/github/callback
https://controller.mergeloom.ai/api/integrations/gitlab/callback
https://controller.mergeloom.ai/api/integrations/azure-boards/callback

Check:

callback URL matches the controller host used in the browser
required OAuth scopes or app permissions are present
the connected account can see the target project, repository, board, team, or space
self-managed GitLab base URL and API URL point to the same instance
Azure Boards and Azure Repos permissions both exist when using Azure for intake and output

See OAuth Callbacks and Scopes.

Validation Fails

Check:

setup commands are correct for the repository
validation commands are correct for the repository
required tools are installed in the worker image
command names are allowed by worker or platform policy
required validation mode is intended
command timeout is long enough

Required setup or validation failures block publish. Advisory validation records the result without necessarily blocking the review request.

Diff Guard Blocks or Warns

Check Workflow settings for:

Diff Guard enabled/disabled state
line-count warning threshold
policy for blocking oversized or risky changes
repository-specific expectations for small PRs/MRs

Diff Guard results appear in audit surfaces. Use them to decide whether the ticket should be split, clarified, or continued with narrower instructions.

PR or MR Is Not Created

Check:

repository is enabled as a writable work repository
GitHub App, GitLab OAuth, or Azure Repos account can push branches
default branch exists
branch protection allows the review flow
validation passed when required
publish-stage provider error is visible in Controller Audit or job detail

If the worker pushed a branch but review creation failed, use Retry Publish only when the job detail shows it as available.

Context Engine Did Not Affect the Run

Check:

Context Engine is enabled for the workspace and plan
the repository is authorized for Context Engine
indexing completed successfully
selected context sources are not quarantined or unavailable
the job audit shows a context pack or a recorded Context Engine unavailable event

Worker execution can continue when Context Engine is unavailable. Treat absence of Context Engine evidence as a context issue, not automatically as a failed code run.

Audit View Looks Empty

Check the execution mode.

Cloud Hosted:

open the customer controller
go to Audit
check Ticket Audit, Code Audit, Context Engine Audit where enabled, and Controller Audit
allow for cloud refresh delay
check plan gates for export or evidence views

Self Hosted:

use the customer controller for Controller Audit
use the Local Worker UI /audit for Ticket Audit
use the Local Worker UI /audit/code for Code Audit
check worker retention settings and local data volume health

See Where to Find Audits.

When to Contact Support

Contact MergeLoom support when the audit evidence does not explain the failure, when a workspace appears blocked by plan or provisioning state, or when a Self Hosted worker repeatedly loses connection after network and credential checks pass.

Include:

workspace name or slug
ticket key, issue URL, or work item URL
job ID if visible
execution mode: Cloud Hosted or Self Hosted
provider path and model, if relevant
target repository alias and code host
PR or MR URL if one exists
screenshot or export from the relevant audit page
Self Hosted: Local Worker UI health status and relevant gateway or executor logs